Skip to content

feat: materialize ambient UCP namespaces - #48

Open
igrigorik wants to merge 2 commits into
mainfrom
feat/ambient-ucp-materialization
Open

feat: materialize ambient UCP namespaces#48
igrigorik wants to merge 2 commits into
mainfrom
feat/ambient-ucp-materialization

Conversation

@igrigorik

Copy link
Copy Markdown
Contributor

Implements the reference schema-resolution behavior for Universal-Commerce-Protocol/ucp#657.

Universal-Commerce-Protocol/ucp#657 reserves an ambient ucp protocol namespace at eligible structured object scopes without requiring every open domain source schema to declare it. This change adds a UCP-aware resolution path that makes the namespace explicit in the resolved schema, allowing existing JSON Schema validators and code generators to consume ordinary JSON Schema without implementing a separate payload walk.

Workflow

UCP source schema                bundled ucp.json#/$defs/members
       │                                      │
       └──────────────────┬───────────────────┘
                          ▼
              ambient namespace pass
              • add optional ucp at eligible structured scopes
              • skip dictionary containers
              • preserve explicit ucp visibility
              • keep the namespace open; reject direct ucp.ucp
                          │
                          ▼
              existing operation resolver
              ucp_request / ucp_response
                          │
                          ▼
              ordinary resolved JSON Schema
                          │
                  ┌───────┴────────┐
                  ▼                ▼
          standard validator   schema/codegen tooling

The materializer installs one collision-safe helper under the operation schema's root $defs and uses absolute root-resource references so nested $id scopes and selected $defs continue to resolve correctly. The existing operation resolver remains responsible for directional annotations.

Category

  • UCP Schema: Changes to the ucp-schema resolver and validator.

Checklist

  • I have followed the contributing guide and Conventional Commits requirements.
  • I have added tests covering the new behavior and edge cases.
  • New and existing tests pass locally.
  • Formatting, linting, and pre-commit checks pass.

Checklist

  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator).
  • I have followed the Contributing Guide
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.

   Implement the reference schema-resolution behavior for
   Universal-Commerce-Protocol/ucp#657.

   Add a UCP-aware resolution path that applies the central namespace vocabulary
   at eligible structured object scopes while excluding dictionaries. Preserve
   namespace openness and directional applicability, reject direct `ucp.ucp`,
   and emit ordinary JSON Schema for existing validators and code generators.

   Keep helper references valid through nested resource IDs and selected
   definitions, extend strict traversal across child-instance applicators, and
   cover directionality, composition, dictionary values, forward compatibility,
   and collision handling.
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status:needs-triage Signal that the PR is ready for human triage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants