Add Descriptor Registry working draft by marcschier · Pull Request #796 · xregistry/spec

marcschier · 2026-11-11T14:44:06Z

Define a reusable, metadata-only Descriptor Resource for identifying representations and shared processing context associated with assets, devices, actors, or multiple entities. The Descriptor model replaces the earlier Context-only and contexturl proposal. CloudEvents event-link selection and the describedby attribute are specified separately in cloudevents/spec#1406.

This draft is based directly on upstream main and contains the Descriptor work, without the other changes in the fork.

Proposed Changes

Add the Descriptor Registry working-draft specification, covering identity, class-typed References, selectors, specialization, publication stability and an optional Descriptor bundle. Ordinary GET remains metadata-only; assembling the bundle requires additional resolver or serving behavior.
Include the Descriptor model, sample, rationale and generated JSON Schema, JSON Structure, Avro and OpenAPI formats.
Add an opt-in --avro-nullable-optionals generator option for Descriptor Avro generation, with regression coverage. Default generation and the existing top-level Schema, Message, Endpoint and CloudEvents Avro artifacts remain unchanged.
Add the draft to the working-drafts index and generation workflow.

Release Note

Add a Descriptor Registry working draft for metadata-only entity descriptions and shared processing context.

Signed-off-by: Marc Schier <marcschier@hotmail.com>

duglin · 2026-11-11T17:00:09Z

+      "resources": {
+        "contexts": {
+          "singular": "context",
+          "hasdocument": false,


changing this to "true", where the doc is then inlined version of the data so people don't need to do any more GETs, would be a nice addition

However, if we do this then ce extension value should include $details so by default they get the non-inlined version. This might make the idea too complex, i can't decide if the presence of $details vs not is something that'll confuse people. Granted, in most cases people will just blindly use the URL provided and not even notice that $details is there.

Pro:

It reuses Core's document vs $details mechanism instead of a negotiated media type.

If the Publisher stores the bundle, the Registry needs no server-side Target retrieval, outbound request policy or combined cache policy.

Con:

On your $details point: the event carries only one of the two URLs. If contexturl includes $details, a Consumer can reach the inlined form only by removing the suffix. That is the URL construction the indirection model was meant to avoid, and §5.1 forbids it. Without $details, every Consumer downloads every Target's content, including Targets it doesn't use.

The bundle is a copy. Each Context Version duplicates its Targets' bytes, a Target change reaches Consumers only after a new document is stored, and Core doesn't check that the document agrees with references.

With a document, Core would also define a contexturl metadata attribute for an externally stored document. Its meaning differs from the CloudEvents attribute's (README open question 1).

If the Registry generates the document instead of the Publisher, we're back to the resolver's retrieval, authorization and caching rules, presented as a document.

The draft therefore keeps the base Context metadata-only. A Registry can serve the inlined form as the resolved view at the same URL, selected by Accept (§7.4). The event URL stays unsuffixed, and Consumers that don't want the bundle never pay for it. Happy to switch if the group prefers the Core document mechanism. I'm leaving this thread open for that discussion.

The problem is that you can't do what's being suggested with a generic xRegistry server. And definitely not with a static file serving xReg endpoint.

duglin · 2026-11-12T09:08:35Z

On the call you mentioned consumers caching the GET results and using a changed url as the indicator that they need to refresh their cache. To do that people would need to either create a new resource for each change to the data or version the resource and use the version url instead of the resource url.

Reject fragments in generated absolute-URL schemas, qualify the root POST example, and distinguish Context views from federation, publication, and WoT profiles. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Require a URI scheme in the generated urlabsolute pattern so validation does not depend on an optional format checker. Clarify Context Version URL caching and record the Context document alternative from review. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier · 2026-11-12T10:15:57Z

Agreed, and that is the model the draft assumes. Per §4.2.4, a Context Version URL identifies one fixed set of references. A Publisher MUST NOT change a Version's references once Producers are configured with its URL. To change them, it creates a new Version and reconfigures the Producers (they are typically the same entity in our use case). §5.1 says contexturl SHOULD identify a Context Version. A Context Resource URL returns the default Version, which can change, so Consumers SHOULD bound how long they cache it.

e46561f makes one caveat explicit in §4.2.4: a new Context Version URL signals changed references, not changed Target content. For the URL to change whenever any context changes, the References also have to identify Target Versions; §4.2.2 already says they SHOULD when the Publisher needs a reproducible interpretation. The Publisher then creates a new Context Version when a Reference has to move to a different Target Version.

Document that the proposed WoT CloudEvents profile uses the Context emitter when contexturl is present and does not fall back to source lookup. Keep other profile behavior out of scope. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Signed-off-by: Marc Schier <marcschier@hotmail.com>

Rework the Context working draft into a metadata-only Descriptor model with Asset/Device, Actor and Context specializations, named class-typed References, messageref/schemaref selectors, publication stability rules, an optional descriptor bundle and informative CloudEvents describedby, WoT and OPC UA guidance. Define explicit bare-name and absolute-URI class syntax. Add a disabled-by-default --avro-nullable-optionals generator option, enable it only for the Descriptor Avro schema, and cover opt-in behavior plus unchanged default output in tools/test_schema_generator.py. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier · 2026-11-14T15:02:02Z

+Message definitions, schemas, WoT Thing Descriptions and OpenUSD assets.
+Asset, Device, Actor and Context Descriptors use the same Resource shape.
+
+This is a working draft related to [xregistry/spec#792][issue792].


Remove this and any references to pull requests. This is normative spec not a design doc or readme. Write this spec in the same style as other Xreg specs.

Removed the provisional-design paragraph and all issue/PR and design-note links from the specification. The abstract now describes the model directly. This revision is local, not pushed yet.

marcschier · 2026-11-14T15:03:44Z

+
+A Descriptor's `references` map gives each representation a local name,
+`class` and absolute `url`. Names select entries; classes state what their
+representations are. Neither assigns an event role. For example, a


Remove "Neither defines...". Negative exclusions statements are mostly useless. If they are not because they are normative rewrite it as a normative single sentence

Removed the event-role exclusion and kept the positive definition: names select entries and classes identify representations. This revision is local, not pushed yet.

marcschier · 2026-11-14T15:04:14Z

+
+Text equivalent: one Descriptor Version names two TDs, one schema and one
+OpenUSD asset. These arrows are References, not containment or ownership.
+Selection of a TD or schema is separate from listing those representations.


What does this mean? Rewrite

Rewrote the diagram explanation to identify each of the four named References and say that the profile selects which ones the Consumer uses for its task. This revision is local, not pushed yet.

marcschier · 2026-11-14T15:04:38Z

+Selection of a TD or schema is separate from listing those representations.
+
+An ordinary `GET` returns all Descriptor metadata, including the References.
+The Consumer retrieves only the representations its task needs. An


"It needs for its tasks"

Changed this to “The Consumer retrieves the representations it needs for its task.” This revision is local, not pushed yet.

marcschier · 2026-11-14T15:05:11Z

+The Consumer retrieves only the representations its task needs. An
+OPTIONAL [Descriptor bundle](#74-descriptor-bundle) can contain
+every direct representation in one response. Bundle assembly requires
+additional serving behavior; Core does not follow References.


Server behavior. Not sure what core sentence means, clarify

Clarified the server behavior: bundle assembly retrieves or assembles the referenced representations under §7.4. Core inline expands contained Groups, Resources and Versions; a Reference URL remains metadata. This revision is local, not pushed yet.

marcschier · 2026-11-14T16:04:26Z

+legal Reference name, not a direct URL. The whole-Thing direct form ends
+in `#`. JSON Pointer and URI-fragment decoding are specified by CE.
+
+The proposed OPC UA binding defines typed shared values, including


This goes into the OPC UA companion spec. I would leave OPC UA only for an example of inline but not normative or profile definition here.

Removed the OPC UA model fragment and normative native-metadata rules. The Context sample still illustrates inline OPC UA extension attributes, explicitly leaving their definitions and protocol mapping to the OPC UA profile. This revision is local, not pushed yet.

The OPC UA Descriptor profile is now defined in OPCF-Members/OPC10100-WoT#124, in source/WoT-PubSub/spec.md, with the dependent Binding mapping aligned to the published CE draft. #796 retains the inline example only; the generic model no longer defines the native fields. The #796 edits remain local.

marcschier · 2026-11-14T16:06:38Z

+- One retrieval MAY supply multiple names with the same URL. The result
+  still has every name and its exact corresponding `url`.
+- The server MUST return every complete direct representation or an error.
+  No omitted, truncated or unauthorized entry is a successful bundle.


Invert the statement

Rewrote this positively: a successful bundle must contain the complete representation for every Reference, with authorization established for each one; otherwise the server must return an error. This revision is local, not pushed yet.

marcschier · 2026-11-14T16:07:13Z

+  No omitted, truncated or unauthorized entry is a successful bundle.
+- The server MUST NOT automatically retrieve `planurl`, `entityid`,
+  `entitytype`, class URIs or links inside Targets. A provenance document
+  can be included only if independently listed as an ordinary named


Provenance document is out of place here

Removed the provenance-document discussion from bundle collection. The rule now simply limits collection to references.*.url and requires additional representations to be listed as named References. This revision is local, not pushed yet.

marcschier · 2026-11-14T16:09:43Z

+but a separately linked schema is not. To include it, a Publisher adds a
+direct `schema` Reference. Schema imports, TD dependencies and OpenUSD
+sublayers or textures do not cause recursive collection. An event's
+`dataschema` is not an input to the bundle request.


Rewrite these negative statements into a normative statement or drop them if they are obvious. Review all of the spec. Similar to my previous feedback

Removed the Message/transitive-dependency/dataschema exclusion paragraph. Relative dependency resolution is now a positive normative rule using the referenced representation's baseurl or url. Reviewed the rest of the spec similarly, retaining concrete validation, security and failure constraints. This revision is local, not pushed yet.

marcschier · 2026-11-14T16:12:47Z

Remove all changelogs or references from previous versions of this doc from it. This is the first and final design.

Removed the earlier-Context/redesign history, compatibility-alias discussion and links to previous review discussions from the rationale and README. The rationale presents the selected design and its trade-offs directly; generator compatibility remains because it describes the current opt-in boundary. This revision is local, not pushed yet.

marcschier added 3 commits November 11, 2026 15:43

Add Event Context Registry working draft

3ac8ef3

Signed-off-by: Marc Schier <marcschier@hotmail.com>

Add Context design rationale to working draft

46c1cb1

Signed-off-by: Marc Schier <marcschier@hotmail.com>

Wrap Context design prose

0081355

Signed-off-by: Marc Schier <marcschier@hotmail.com>

duglin reviewed Nov 11, 2026

View reviewed changes

marcschier added 2 commits November 12, 2026 11:02

Clarify Context draft boundaries and URL validation

5127c61

Reject fragments in generated absolute-URL schemas, qualify the root POST example, and distinguish Context views from federation, publication, and WoT profiles. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Align Context draft with WoT emitter precedence

49f7d17

Document that the proposed WoT CloudEvents profile uses the Context emitter when contexturl is present and does not fall back to source lookup. Keep other profile behavior out of scope. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier marked this pull request as ready for review November 12, 2026 12:06

marcschier added 3 commits November 12, 2026 13:13

Remove Context example test and related references

36f2ce2

Signed-off-by: Marc Schier <marcschier@hotmail.com>

Clarify resolved Context view server requirements

56f2a75

Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier changed the title ~~Add Event Context Registry working draft~~ Add Descriptor Registry working draft Nov 14, 2026

marcschier commented Nov 14, 2026

View reviewed changes

marcschier mentioned this pull request Nov 14, 2026

Relocate WoT Descriptor profile above upstream #571 marcschier/xregistry-drafts#8

Draft

Conversation

marcschier commented Nov 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcschier Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

duglin commented Nov 12, 2026

Uh oh!

marcschier commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marcschier commented Nov 11, 2026 •

edited

Loading

marcschier Nov 12, 2026 •

edited

Loading

marcschier commented Nov 12, 2026 •

edited

Loading