[avillar]

What

Annotated schemas now carry a root-level x-bblocks-metadata object recording which bblock (and register) they were generated from. This lets bblocks-aware tooling identify a schema even if its URL is aliased, redirected or mirrored, or if the schema is encountered out of context (e.g. referenced by a non-bblock schema).

Example, from an annotated schema:

x-bblocks-metadata:
  itemIdentifier: ogc.bbr.examples.rules.topo-edges
  register: http://localhost:9090/register/build-local/register.json
  version: '1.0'
  dateOfLastChange: '2026-09-18'

• itemIdentifier: the strong key; globally unique through the register's prefix.
• register: URL of the published register.json. Only included when --base-url is set. It is a hint: clients may ignore it and resolve the bblock from its identifier in some other way (e.g. a meta-register).
• version / dateOfLastChange: let a client judge staleness. The date is the existing git-derived dateOfLastChange, not a generation time, so unchanged bblocks keep producing identical output. A client that cares about $ref'd dependencies can trace them itself.

The key is a provenance claim, not proof: clients decide whether to trust it. It is written to the YAML, JSON and OAS 3.0 outputs, on both the normal annotation path and the extensionPoints path. If a source schema already has an x-bblocks-metadata object, extra keys in it are kept and the four generated keys override. It is applied to schemas only (not JSON-LD contexts, where an unknown x- key would be parsed as a term definition).

Other changes

• dateOfLastChange used to be computed in do_postprocess(), after annotation. That logic moved into resolve_date_of_last_change() (behavior unchanged), which is now also called at the start of the annotate step so the date is available when the schema is written.
• BuildingBlockRegister takes a new optional register_url.
• New unit tests in tests/test_bblocks_metadata.py.

Testing

• Full unit suite passes.
• Ran the postprocessor against a copy of bblocks-examples on this branch and on master: both exit 0, produce the same set of output files and the same 13 pre-existing tracebacks (unresolvable $defs pointers and an intentional jq-error transform test). All 24 annotated schemas on this branch have the new key.

Downstream impact

• One-time churn: the first build after a release containing this will modify every annotated schema in every downstream register's auto-committed build/ output, since they all gain the new key. This is expected, and easy to spot as the only change in that commit.
• As usual, nothing reaches @v1-pinned consumers until a new release tag is cut; merging to master alone doesn't change production behavior.

cc @rob-metalinkage

[rob-metalinkage]

Looks sensible.