Markdown Version | Transcript | Session Recording | Session Materials

JSONSCHEMA

Summary

The JSONSCHEMA Working Group met at IETF 126 to discuss the progress of its core document, draft-ietf-jsonschema-json-schema. The session focused on improving the readability of the specification through additional practical examples, refining terminology (specifically "JSON value" versus "JSON text"), restructuring the concept of annotations around the "result info set," and clarifying the behavior of the default keyword. The Area Director, Andy Newton, emphasized the importance of meeting the May 2027 milestone due to downstream dependencies in other Standards Development Organizations (SDOs).

Key Discussion Points

Working Group Scope and Milestones

Paul Hoffman opened the meeting using the Chair slides. He reminded participants that the working group's charter focuses on standardizing the adopted input document, draft-ietf-jsonschema-json-schema, rather than introducing major new features.

Responsible Area Director Andy Newton highlighted that other SDOs and IETF working groups are already taking normative references to JSON Schema. He encouraged the group to meet or beat its May 2027 milestone. Paul Hoffman noted that finishing the current chartered work efficiently is a prerequisite for any future rechartering to address new features.

Draft Status and Examples

Lisa Dusseault presented the JSON Schema Draft Status, issues and next work slides.

• Target Audiences: The draft is being structured to address three distinct readers in sequence: Schema Authors, Schema Implementers, and Schema Extenders.
• Examples: Sections 4 and 5 of the draft have been populated with practical, domain-specific examples (e.g., 2D coordinates, meeting invitations) to illustrate both the syntax and the practical "why" behind various keywords.

Terminology: "JSON Value" vs. "JSON Text"

The group discussed aligning terminology with existing standards like JSONPath (RFC 9535):

• Lisa Dusseault proposed using "JSON value" to describe parsed data structures (the data model) instead of "JSON text," which implies raw byte streams. This accommodates applications that process parsed representations (e.g., Python dicts) without forcing implementations to handle physical serialization details.
• Carsten Bormann and Austin Wright supported "JSON value" because it abstracts away physical variations. For example, in chat, Carsten Bormann and Andrew Newton noted that different JSON texts (e.g., 1.000 vs 1.0) resolve to equivalent JSON values.
• Informative references to ECMAScript (ECMA) standards were proposed to illustrate mappings between byte streams and programming language constructs.

Annotations and the "Result Info Set"

• Complexity: Elliot noted that annotations remain highly complex for average readers and suggested introducing them via a simple, inline "build out" starting with basic examples. Paul Hoffman and Elliot agreed this clarification belongs inline in the main body of the text.
• Result Info Set: Henry Andrews and Lisa Dusseault discussed framing annotations around a "result info set" (the cross-product of the schema, its annotations, and the input instance). Henry Andrews noted that structuring this concept clarifies when data is added to or removed from validation outputs.
• Pipeline Use Cases: Carsten Bormann cautioned that annotations turn JSON Schema from a recognition language into a transformation language. Lisa Dusseault and Austin Wright clarified that annotations themselves do not transform data; instead, they output metadata that downstream pipeline tools can use to perform transformations or auditing. Henry Andrews shared that OpenAPI uses annotations in this manner for context-sensitive validation (such as readOnly fields).

Redefining the default Keyword

• Lisa Dusseault proposed redefining default as a standard validation keyword rather than an annotation, as it does not behave like a typical annotation when an instance field is missing.
• Compatibility Concerns: Bengo raised concerns that changing default from an annotation to a standard keyword might break existing metaprogramming libraries and tools (such as those integrated with OpenAPI). He advised notifying library maintainers early.
• Henry Andrews clarified that any current tools that modify instances by filling in defaults are operating outside the core specification, as the current draft contains no normative requirements for implementations to modify instances based on default.
• Austin Wright suggested that if interoperability issues persist, the group could consider splitting default into more specific keywords (e.g., defining sensible starting templates vs. handling missing values).

Extensibility, Vocabularies, and Versioning

Lisa Dusseault raised the topic of meta-schemas and extensibility:

• $schema vs $id: The $schema keyword is utilized to declare meta-schema dependencies and act as a versioning marker.
• Vocabularies: Vocabularies allow for "multiple inheritance" in meta-schemas, enabling users to combine base specifications (e.g., Draft 2020-12) with specialized domain schemas, such as geofence/geospatial schemas.

Quality and Style Cleanups

• Rowan May recommended performing a sweep of the document to address "unmotivated shoulds" (either providing clear rationale or moving them to an implementer's appendix) and suggested expanding the regular expressions section.
• Carsten Bormann advised the working group to apply "taste" to find a middle ground between codifying every historical implementation mistake and overly restricting the existing community.

Decisions and Action Items

• Terminology Direction: There was general agreement to adopt the term "JSON value" (consistent with RFC 9535) to refer to the post-parsed data model.
• Action Item (Lisa Dusseault): Continue integrating inline examples and simplifying the explanation of annotations using a progressive "build out" approach.
• Action Item (Lisa Dusseault / Henry Andrews): Draft the proposed redefinition of the default keyword and solicit feedback from the broader JSON Schema library maintainer community regarding potential backwards-compatibility impacts.
• Action Item (WG): Review the Security Considerations section of draft-ietf-jsonschema-json-schema and share feedback on the mailing list.

Next Steps

• Mailing List Discussion: Deepen the technical discussion regarding the "result info set" structure, the default keyword restructuring, and the cleanup of unmotivated SHOULD statements.
• Document Revision: Prepare the next revision of draft-ietf-jsonschema-json-schema incorporating the terminology updates and structural changes.

Related Documents

draft-ietf-jsonschema-json-schema, draft-status-issues-and-next-work-00