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 status:needs-triage Signal that the PR is ready for human triage status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 7, 2026
@damaz91 damaz91 added status:stale-review Applied if a PR is waiting on a reviewer for too long and removed status:under-review labels Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status:stale-review Applied if a PR is waiting on a reviewer for too long

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants