Refine Structure of Spec

[PascalSenn]

Vote for what you prefer:

👀 flat :

• 3. Schema Composition (use section this more to describe the process)
• 4. Validate Source Schemas
• 5. Pre-Merge Validation
• 6. Merge Validation
• 7. Post-Merge Validation
• 8. Validate Composite Schema Satisfiability

🚀 Nested 3.1:

• 3.1.1 Validate Types
• 3.1.2 Validate Enums
• 3.1.3 Validate Directives
• 3.1.4 ...

❤️ Flat Schema Composition

• 3 Schema Composition (use section this more to describe the process)
  • 3.1 Validate Source Schemas
  • 3.2 Pre-Merge Validation
  • 3.3 Merge Validation
  • 3.4 Post-Merge Validation
  • 3.5 Validate Composite Schema Satisfiability

🎉 : Nested Schema Composition

• 3 Schema Composition (use section this more to describe the process)
  • 3.1 Validate Source Schemas
  • 3.2 Merge
    • 3.2.1 Pre-Merge Validation
    • 3.2.2 Merge
    • 3.2.3 Post-Merge Validation
  • 3.3 Validate Composite Schema Satisfiability

😄 : Combined version from @benjie

3 Schema Composition
  3.1 Validate Source Schemas
  3.2 Pre-Merge Validation
      3.2.1 Validate Enums
            3.2.1.1 Enum Type Default Value Is Accessible
  3.3 Merge
      3.3.1 Merge Scalar Types
      3.3.2 Merge Interface Types
  3.4 Post-Merge Validation
      3.4.1 Validate Field Directives
            3.4.1.1 Required Fields Must Exist
            3.4.1.2 Shareable Only On Object Fields
  3.5 Validate Composite Schema Satisfiability

[smyrick]

My proposed structure

• 3 Schema Composition (use section this more to describe the process)
  • 3.1 Validate Source Schemas
  • 3.2 Pre-Merge Validation
  • 3.3 Merge Validation
  • 3.4 Post-Merge Validation
  • 3.5 Validate Composite Schema Satisfiability

@benjie Also suggests with this structure we can nest 3.1 further with

• 3.1.1 Validate Types
• 3.1.2 Validate Enums
• 3.1.3 Validate Directives
  ...etc

[benjie]

Yeah I voted ❤️ 🚀 for a combination:

3 Schema Composition
  3.1 Validate Source Schemas
  3.2 Pre-Merge Validation
      3.2.1 Validate Enums
            3.2.1.1 Enum Type Default Value Is Accessible
  3.3 Merge
      3.3.1 Merge Scalar Types
      3.3.2 Merge Interface Types
  3.4 Post-Merge Validation
      3.4.1 Validate Field Directives
            3.4.1.1 Required Fields Must Exist
            3.4.1.2 Shareable Only On Object Fields
  3.5 Validate Composite Schema Satisfiability

[PascalSenn]

@benjie @glen-84 I have added this option to the vote

[benjie]

Another subtle change I'd recommend (and you may see this in my example above) is try and make your rule names state positive assertions "This Fact Is True" rather than failure conditions "This Bad Thing Happened".

For example "Enum Type Default Value Uses Inaccessible Value" sounds like you're asserting that enum type default values must use an inaccessible value. Instead: "Enum Type Default Value Is Accessible" is a better name (assuming it's accurate?) - the validation checks that the enum type's default value is accessible.

[glen-84]

Should we add an extra stage at the beginning named "Parse Source Schemas", which parses the source schemas and may return INVALID_GRAPHQL? (it would replace 3.2.1.28 Invalid GraphQL)

I ask because from the "Validate Source Schemas" stage, you're usually working with already-parsed schemas.

The alternative is for the "Validate Source Schemas" stage to take the SDL and return the parsed schemas, but that seems less elegant, as it would be the only one of 4 validation stages that returns something.