Schemas

The shapes the operations read and return, as the document declares them. A property whose type is another schema links to it rather than repeating it, because it is one shape and not several.

Attempt

One line of the service log: one try at one delivery.

(object, no other properties)

Property
at	When it was tried. (string, required)
attempt	1 to 5. (integer, required)
delivery	(string, required)
endpoint	(string, required)
error	(string or null, required)
outcome	(string, required, one of delivered, failed)
retry_at	When this delivery becomes due again, or null when it landed or has used all 5 attempts. The schedule after the first attempt is 60, 300, 1800, 7200 seconds. (string or null, required)
status	The subscriber’s status code, or null where no response was had at all. A 4xx or a 5xx is a refusal rather than an absence and is retried the same. (integer or null, required)
subscription	(string, required)

AttemptList

(object, no other properties)

Property
attempts	(array of Attempt, required)

Change

One atom change of one published release.

(object, no other properties)

Property
atom	The obligation atom that moved. (string, required)
change	The manifest’s own word: added, changed, removed or deprecated. (string, required)
citation	The change’s citation, copied out of the release’s diff manifest unaltered. Its shape is the release plane’s — an eId, the quoted text and the character span it occupies in the source — and this service restates none of it. (object, required)
classification	Substantive or editorial, copied from the manifest. The release plane decided it from the amending act’s own recitals, and this service does not re-decide it: a second reading would eventually disagree with the one the release shipped, and a consumer could not tell which was the release’s answer. (string, required)
classification_basis	Why the classification is what it is, again the manifest’s own. (string, required)
detail	What the change was, as the manifest states it: the atom before and after, and the amending instruction responsible. (object, required)
facets	What a filter is written against. The manifest states none of it: entity_types is the atom’s applies_to and jurisdiction is that of the unit the atom cites, both read out of the release’s own corpus bundle once at publication and stored — so a feed request is a query, and the feed keeps saying what it said after the checkout has moved on. (object, required, no other properties)
facets.entity_types	(array of string, required)
facets.jurisdiction	(array of string, required)
facets.regime	(string, required)
facets.topics	(array of string, required)
id	openregs:<regime>@<tag>:<atom id> — permanent, and a function of the release and the atom, so re-announcing a release cannot make an old change look new. A reader that has seen this id has seen this change. (string, required)

Delivery

One payload owed to one subscriber. The payload bytes are not in it: they are in the store, and what a reader of this endpoint needs is the state and the schedule.

(object, no other properties)

Property
attempts	How many attempts have been made. (integer, required)
created_at	(string, required)
event	(string, required, one of release.published)
id	A function of the subscription and the payload bytes, so it is stable across a re-announcement and worth deduplicating on. It travels on the X-OpenRegs-Delivery header of the POST. (string, required)
last_error	(string or null, required)
next_attempt_at	When it becomes due again; null when it is not waiting. (string or null, required)
regime	(string, required)
signature	sha256=<hex> over the payload bytes. (string, required)
state	(string, required, one of delivered, exhausted, pending)
subscription	(string, required)
tag	(string, required)

DeliveryList

(object, no other properties)

Property
deliveries	(array of Delivery, required)

DiffManifest

The release’s own diff manifest, served verbatim. Its shape belongs to the release plane, which is why this schema is open: it names the members a client needs to navigate and leaves the rest to the artifact.

(object)

Property
changes	Every change the release reported, atom and unit alike. The feed fans out only the atom ones; both are here, because this is the manifest and not a projection of it. (array of any, required)
regime	(string, required)
tag	(string, required)

Error

The one refusal shape this service uses, on every failure path it owns. It carries a sentence and nothing else: no code to branch on and no correlation id, which is a real difference from the serving API and is stated here rather than left for a client to discover. The one refusal not in this shape is the standard library’s 501 for a method the handler implements nothing for, which is HTML and belongs to no route.

(object, no other properties)

Property
error	What went wrong, in words a caller can act on. (string, required)

Fanout

What one publication announced, owed, and managed to hand over.

(object, no other properties)

Property
attempts	The first attempt at each delivery, made inline. (array of Attempt, required)
deliveries	Created by this publication, in subscription order. (array of Delivery, required)
publication	(Publication, required)
silent	Subscriptions this release matched nothing for, and which were therefore not written to. Named rather than omitted, because ‘nobody heard’ and ‘this one did not’ are different answers. (array of string, required)

FeedIndex

(object, no other properties)

Property
base_url	What the links in this instance’s feeds are written against. It is the bound address unless --base-url said otherwise, which is what a deployment behind a proxy sets. (string, required)
feeds	(object, required, no other properties)
feeds.json	(string, required)
feeds.rss	(string, required)
filters	The dimensions a filter may name. (array of string, required)
service	(string, required)
signature	How to verify a delivery, said where a subscriber will look. (object, required, no other properties)
signature.algorithm	(string, required)
signature.header	(string, required)
signature.over	(string, required)

Filter

The four dimensions a subscription or a feed request may narrow on, each a sorted list of terms. A dimension left empty matches everything; a dimension with terms matches a change carrying any of them, and every named dimension must match — so a filter is an and of ors.

entity_type is the one dimension where membership is not the test: the taxonomy’s parent relation decides, so an obligation declared on a broader type reaches a subscription for a narrower one and not the other way round. topic matches nothing today, because no atom in the corpus carries a subject vocabulary yet; it is wired rather than removed so that subscriptions written against it start matching the day one lands.

(object, no other properties)

Property
entity_type	(array of string, required)
jurisdiction	(array of string, required)
regime	(array of string, required)
topic	(array of string, required)

JsonFeed

A JSON Feed 1.1 document. Its members are the JSON Feed specification’s and are not restated here; the schema names version and items because a client needs them to navigate, and describes the _openregs member because that one is this project’s, in the _-prefixed namespace the specification reserves for extensions.

(object)

Property
_openregs	The filter this document was rendered for, echoed back. (object, no other properties)
_openregs.filter	(Filter, required)
_openregs.schema_version	(integer, required)
items	(array of JsonFeedItem, required)
version	(string, required)

JsonFeedItem

One JSON Feed item. title, content_text, date_published and tags are the specification’s members, carried as it defines them.

(object)

Property
_openregs	The change in the same shape a webhook payload states it, so a consumer that polls the feed and a consumer that is pushed to read one document and not two. (object, no other properties)
_openregs.change	(Change, required)
_openregs.release	(ReleaseRef, required)
id	The feed item id; see Change.id. (string, required)
url	The release’s diff manifest on this service, with the atom id as the fragment. A link and not a decoration: it resolves. (string, required)

Publication

One release this service has announced.

(object, no other properties)

Property
as_of	(string, required)
built_at	(string, required)
changes	How many atom changes were announced. (integer, required)
commit	(string, required)
diff_manifest	(string, required)
published_at	When this service was told about the release. A genuine event, and the reason it is stored and not what an item is dated by. (string, required)
regime	(string, required)
tag	(string, required)

PublishRequest

Which built release to announce. A member this operation does not read is ignored rather than refused — see the operation’s request body.

(object)

Property
regime	The regime whose release this is. (string, required)
tag	The release tag, as it was built. (string, required)

ReleaseRef

The release a change was announced from.

(object, no other properties)

Property
as_of	The date the release’s texts speak from. (string, required)
built_at	That commit’s committer date, and every date this feed publishes. A feed entry is content, and content derived from a commit is dated by it. (string, required)
commit	The canon commit it was compiled from. (string, required)
diff_manifest	The manifest filename inside the release directory. (string, required)
regime	(string, required)
tag	(string, required)

RssFeed

An RSS 2.0 document with an Atom self-link. RSS is a specified format and is not restated here.

(string)

Subscription

A registered subscription. The signing secret is deliberately not a property of this schema, because it is in no response.

(object, no other properties)

Property
active	Whether a publication fans out to it. (boolean, required)
created_at	When the registration happened — a real moment, and one of the two things in this service that a commit cannot date. (string, required)
endpoint	Where a matching change is POSTed. (string, required)
filter	(Filter, required)
id	Minted as sub-0001 when none was given. (string, required)
name	Defaults to the endpoint. (string, required)

SubscriptionCreated

(object, no other properties)

Property
subscription	(Subscription, required)

SubscriptionList

(object, no other properties)

Property
subscriptions	(array of Subscription, required)

SubscriptionRegistration

What a registration states. A member this operation does not read is ignored rather than refused; the one thing inside it that is refused is a filter naming something that is not a dimension.

(object)

Property
active	Defaults to true. (boolean)
endpoint	An http(s) URL. Cleartext http only to loopback — see the operation’s description for why. (string, required)
filter	A filter as a caller writes it. Any dimension may be omitted, and a bare string is read as a one-element list. A key that is not a dimension is refused, not ignored — this is the one place in a request body where that is true, and it is true because a subscriber who misspells a dimension and is quietly registered for everything has been widened without being told. The schema is left open rather than closed because the service reads a plural by stripping trailing letters, so the exact set of spellings it tolerates is wider than the eight named here, and a schema claiming a refusal the service does not make would be the first false sentence in this document. (object)
filter.entity_type	One entity_type term or a list of them. Both the singular and the plural spelling are read. (any)
filter.entity_types	One entity_type term or a list of them. Both the singular and the plural spelling are read. (any)
filter.jurisdiction	One jurisdiction term or a list of them. Both the singular and the plural spelling are read. (any)
filter.jurisdictions	One jurisdiction term or a list of them. Both the singular and the plural spelling are read. (any)
filter.regime	One regime term or a list of them. Both the singular and the plural spelling are read. (any)
filter.regimes	One regime term or a list of them. Both the singular and the plural spelling are read. (any)
filter.topic	One topic term or a list of them. Both the singular and the plural spelling are read. (any)
filter.topics	One topic term or a list of them. Both the singular and the plural spelling are read. (any)
id	Minted when absent; must not already exist. (string)
name	Defaults to the endpoint. (string)
secret	The key deliveries to this endpoint are signed with. Held by this service and by the subscriber, and returned by no response. (string, required)

SubscriptionRemoved

(object, no other properties)

Property
removed	The id that is now gone. (string, required)

WebhookPayload

The document POSTed to a subscriber. Its bytes are a function of the release and the filter — sorted keys, two-space indent, one trailing newline — which is what makes the signature reproducible and the delivery id stable.

(object, no other properties)

Property
changes	Only the changes this subscription’s filter matched. (array of Change, required)
counts	(object, required, no other properties)
counts.changes	(integer, required)
event	(string, required)
filter	(Filter, required)
release	(ReleaseRef, required)
schema_version	(integer, required)
subscription	Which subscription this delivery answers. (string, required)