Skip to content

Clarify $uses placement and effective-schema processing #36

Description

@clemensv

Problem

The Core description of $uses is not sufficiently precise for interoperable instance validation.

It says $uses is available only in instance documents, while also saying that it may be used in a meta-schema referencing a parent schema. Its value is described as add-in names or JSON Pointers, but the placement, lookup context, failure behavior, and effect on the root effective schema need a single normative algorithm.

This matters for closed root objects: $uses is document-control metadata, but accepting it without applying and validating the selected add-ins silently under-validates the instance.

Decisions required

  1. Define every document kind and location where $uses is permitted.
  2. Define the allowed value shape, uniqueness requirements, and whether an empty set is valid.
  3. Define resolution of offered names and same-document JSON Pointers for each permitted document kind.
  4. Require an error for unknown, malformed, conflicting, or inapplicable add-ins.
  5. Define how selected add-ins produce the effective root schema, including properties, required, and additionalProperties.
  6. State that $uses is excluded from application-property matching only after its own validation and application.
  7. State whether validation APIs may mutate the input instance while processing $uses.

Acceptance criteria

  • Core provides a deterministic $uses processing algorithm.
  • Root-only and meta-schema cases are unambiguous.
  • Closed-root examples cover valid, unknown, malformed, and conflicting add-ins.
  • The Core meta-schema and SDK conformance assets reflect the resolved rules.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions