diff --git a/core/spec.md b/core/spec.md
index 209d9aa..5068bbe 100644
--- a/core/spec.md
+++ b/core/spec.md
@@ -40,7 +40,7 @@ automation and tooling.
- [Creating or Updating Versions](#creating-or-updating-versions)
- [Retrieving a Version](#retrieving-a-version)
- [Deleting Versions](#deleting-versions)
- - [Configuring Responses[#configuring-responses]
+ - [Configuring Responses](#configuring-responses)
- [Inline](#inline)
- [Filter](#filter)
- [Compact](#compact)
@@ -232,7 +232,7 @@ For easy reference, the JSON serialization of a Registry adheres to this form:
"self": "URL", # URL to "meta" object
"shortself": "URL", ?
"xid": "URI",
- "xref": "URL", ? # Ptr to linked Resource
+ "xref": "URL", ? # xid of linked Resource
"epoch": UINTEGER, # Resource's epoch
"createdat": "TIMESTAMP", # Resource's
"modifiedat": "TIMESTAMP", # Resource's
@@ -407,11 +407,13 @@ be one of the following data types:
- See [Serializing Resource Documents](#serializing-resource-documents)
for more information about serializing maps as HTTP headers.
- `object` - a nested entity made up of a set of attributes of these data types.
-- `relation` - a relative URL reference to a type of entity in the Registry.
- This type of attribute is used in place of `url` so that the Registry can
- do "type checking" to ensure the value references the correct type of
- Registry entity. See the definition of the [`target` model
- attribute](#model.target) for more information.
+- `relation` - MUST be a `URL` (xid) reference to another entity defined within
+ the Registry. The actual entity attribute value MAY reference a non-existing
+ entity (i.e. dangling pointer), but the syntax MUST reference a
+ defined/valid type in the Registry. This type of attribute is used in
+ place of `url` so that the Registry can do "type checking" to ensure the
+ value references the correct type of Registry entity. See the definition of
+ the [`target` model attribute](#model.target) for more information.
- `string` - sequence of Unicode characters.
- `timestamp` - an [RFC3339](https://tools.ietf.org/html/rfc3339) timestamp.
- `uinteger` - unsigned integer.
@@ -424,6 +426,11 @@ be one of the following data types:
- `url` - URL as defined in
[RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738).
+All relative URIs and URLs that reference entities within the Registry MUST
+begin with `/` and MUST be relative to the root path of the Registry service.
+The root path of a Registry service MAY be at the root of a host or have a
+`PATH` portion in its URL (e.g. `http://example.com/myregistry`)
+
The "scalar" data types are: `boolean`, `decimal`, `integer`, `relation`,
`string`, `timestamp`, `uinteger`, `uri`, `urireference`, `uritemplate`, `url`.
Note that `any` is not a "scalar" type as its runtime value could be a complex
@@ -520,8 +527,8 @@ The definition of each attribute is defined below:
- Constraints:
- MUST be a non-empty string consisting of [RFC3986 `unreserved`
characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3)
- (ALPHA / DIGIT / "-" / "." / "_" / "~") and `@`, MUST start with
- ALPHA, DIGIT or "_" and MUST be between 1 and 128 characters in length.
+ (ALPHA / DIGIT / `-` / `.` / `_` / `~`) and `@`, MUST start with
+ ALPHA, DIGIT or `_` and MUST be between 1 and 128 characters in length.
- MUST be case insensitive unique within the scope of the entity's parent.
In the case of the `registryid` for the Registry itself, the uniqueness
scope will be based on where the Registry is used. For example, a publicly
@@ -556,7 +563,7 @@ of the existing entity. Then the existing entity can be deleted.
##### `self` Attribute
- Type: URL
-- Description: A server generated unique absolute URL for an entity. In the
+- Description: A server generated unique URL for the current entity. In the
case of pointing to an entity in a [Registry
Collection](#registry-collections), the URL MUST be a combination of the
base URL for the collection appended with the `SINGULARid` of the entity.
@@ -575,7 +582,8 @@ of the existing entity. Then the existing entity can be deleted.
- Constraints:
- MUST be unique across all entities in the Registry.
- - MUST be a non-empty absolute URL.
+ - MUST be a non-empty absolute URL, except when `?compact` is enabled
+ then it MUST be a relative URL.
- MUST be a read-only attribute in API view.
- Examples:
- `https://example.com/registry/endpoints/ep1`
@@ -623,7 +631,7 @@ of the existing entity. Then the existing entity can be deleted.
Unlike `SINGULARid`, which is unique within the scope of its parent, `xid`
MUST be unique across the entire Registry, and as such is defined to be a
relative URL from the root of the Registry. This value MUST be the same as
- the PATH portion of the `self` URL, after the Registry's base URL, without
+ the PATH portion of its `self` URL, after the Registry's base URL, without
any `$` suffix (e.g. `$details`).
This attribute is provided as a convenience for users who need a reference
@@ -981,11 +989,13 @@ to their respective forms as follows:
Where:
- The term `COLLECTIONS` MUST be the plural name of the collection
(e.g. `endpoints`, `versions`).
-- The `COLLECTIONSurl` attribute MUST be an absolute URL that can be used to
- retrieve the `COLLECTIONS` map via an HTTP(s) `GET` (including any necessary
- [filtering](#filter)) and MUST be a read-only attribute that MUST be silently
- ignored by a server during a write operation. An empty collection MUST
- return an HTTP 200 with an empty map (`{}`).
+- The `COLLECTIONSurl` attribute MUST be a URL that can be used to retrieve
+ the `COLLECTIONS` map via an HTTP(s) `GET` (including any necessary
+ [filtering](#filter)) and MUST be a read-only attribute that MUST
+ be silently ignored by a server during a write operation. An empty
+ collection MUST return an HTTP 200 with an empty map (`{}`). This attribute
+ MUST be an absolute URL except when `?compact` is enabled and the collection
+ is inlined, in which case it MUST be a relative URL.
- The `COLLECTIONScount` attribute MUST contain the number of entities in the
`COLLECTIONS` map (after any necessary [filtering](#filter)) and MUST
be a read-only attribute that MUST be silently ignored by a server during
@@ -2010,6 +2020,11 @@ different set of changes are more appropriate:
- Timestamp: zero (00:00:00 UTC Jan 1, 1970).
- If valid, String attributes SHOULD use `"undefined"`.
+Changes to the model MUST NOT include changing the `hasDocument` aspect of a
+Resource from `false` to `true` if there are attributes defined on that
+Resource whose names conflict with the `RESOURCE*` attributes. Any attempt do
+to so MUST generate an error.
+
If a backwards incompatible change is needed, and the existing entities need
to be preserved, then it is RECOMMENDED that users define a new Group or
Resource types for future instances of those entities.
@@ -2101,10 +2116,16 @@ The following describes the attributes of Registry model:
- Values MAY be empty strings.
- The following labels are defined for convenience and MAY also be used
as labels for Groups or Resource model types:
+ - Name: `modelversion`
+ Value: The version of the model. For many specifications it's a
+ combination of major and minor version numbers, e.g. `1.2`.
+ This label will most likely only appear as a label on the model itself,
+ not on Groups or Resource model definitions.
- Name: `compatiblewith`
- Value: A URI reference to Registry that this Registry's model is
+ Value: An absolute URL to the model specification that this model is
compatible with. This specification does not mandate any runtime
validation of this claim.
+ - Model authors MAY define additional labels.
- `attributes`
- The set of attributes defined at the indicated level of the Registry. This
@@ -2154,7 +2175,9 @@ The following describes the attributes of Registry model:
- `attributes."STRING".target`
- The type of entity that this attribute points to when `type` is set to
- `relation`. The value of this model attribute MUST be one of:
+ `relation`, `url-reference` or `uri-reference`. `target` MUST NOT be used
+ for any other type of attribute. The value of this model attribute MUST be
+ a "xid template" of one of the following forms:
- `/GROUPS` - a plural Group type name. An entity attribute of this
type/target MUST reference an instance of this Group type.
- `/GROUPS/RESOURCES` - a plural Resource type name. An entity attribute
@@ -2167,12 +2190,19 @@ The following describes the attributes of Registry model:
attribute of this type/target MUST reference an instance of a Version
of this Resource type, not the Resource itself.
- Example: `/endpoints/messages`
- - An entity attribute of type `relation` MUST use the `xid` value of the
- entity to which it points. For example, a `target` value of `/endpoints`
- might result in an entity attribute value of `/endpoints/e1`.
+ - A `relation` entity attribute that includes a `target` value as part of
+ its model definition MUST match the `target` entity type specified. A
+ `relation` attribute that does not include `target` definition has no
+ such restriction and MAY be any valid `xid` value.
+ - A URI/URL-reference entity attribute MAY include `target` as part of its
+ definition. If so, then any runtime value that is a relative URI/URL
+ (begins with `/`) MUST be an `xid` and MUST adhere to the `target` entity
+ type specified. Absolute URIs/URLs are not constrained by the presence of
+ a `target` value.
- Type: STRING.
- - REQUIRED if `type` is "relation".
- - MUST NOT be used when `type` is not "relation".
+ - To keep the model, and processing simple, the value MUST NOT reference a
+ type that uses `ximport` to reference another model entity definition. In
+ other words, `target` is not transitive.
- `attributes."STRING".description`
- A human readable description of the attribute.
@@ -3477,7 +3507,7 @@ However, there a few exceptions:
attribute (in the `meta` sub-object) can be used to locate the "default"
Version.
- `shortself`, if present, MUST be an alternative URL for `self`.
-- `xid` MUST be a relative URL to the Resource, and not to the "default"
+- `xid` MUST be a relative URI to the Resource, and not to the "default"
Version in the `versions` collection.
- A few extra attributes will appear to help with the navigation of the
Resource. For example, a URL to the `meta` sub-object and the `versions`
@@ -3610,7 +3640,6 @@ Resource attribute MUST adhere to the following:
"modifiedat": "TIMESTAMP", # Resource's
"readonly": BOOLEAN, ? # Default is "false"
"compatibility": "STRING", ? # Default is "none"
- # TODO - add timestamp?
"defaultversionid": "STRING",
"defaultversionurl": "URL",
@@ -3633,7 +3662,7 @@ MUST appear as HTTP headers and adhere to the following:
xRegistry-RESOURCEid: STRING
xRegistry-versionid: STRING
xRegistry-self: URL
-xRegistry-xid: URL
+xRegistry-xid: URI
# Default Version attributes, and other HTTP headers, appear here
xRegistry-metaurl: URL
xRegistry-versionsurl: URL
@@ -3656,7 +3685,7 @@ The Resource level attributes include the following
and the following Resource level attributes:
##### `xref` Attribute
-- Type: Relative URL from base URL of Registry
+- Type: Relative URL (xid) of a same-typed entity in the Registry.
- Description: indicates that this Resource is a reference to another Resource
within the same Registry. See [Cross Referencing
Resources](#cross-referencing-resources) for more information.
@@ -3741,7 +3770,7 @@ and the following Resource level attributes:
##### `defaultversionurl` Attribute
- Type: URL
-- Description: an absolute URL to the default Version of the Resource.
+- Description: a URL to the default Version of the Resource.
The Version URL path MUST include `$details` if the request asked for
the serialization of the Resource metadata. This would happen when
@@ -3751,8 +3780,10 @@ and the following Resource level attributes:
- REQUIRED in responses, OPTIONAL in requests.
- OPTIONAL in document view.
- MUST be a read-only attribute in API view.
- - MUST be an absolute URL to the default Version of the Resource, and MUST.
- be the same as the Version's `self` attribute.
+ - MUST be an absolute URL to the default Version of the Resource, and MUST
+ be the same as the Version's `self` attribute, except when `?compact`
+ is enabled, and the Version is present in the response, then it MUST be a
+ relative URL.
- Examples:
- `https://example.com/endpoints/ep1/messages/msg1/versions/1.0`
@@ -3824,15 +3855,17 @@ no changes are to be made to the `meta` sub-object.
##### `metaurl` Attribute
- Type: URL
-- Description: an absolute URL to the Resource's `meta` sub-object. This
- sub-object will contain most of the Resource level attributes.
+- Description: a URL to the Resource's `meta` sub-object. This sub-object will
+ contain most of the Resource level attributes.
- Constraints:
- If present, it MUST appear as an attribute of the Resource as a sibling
to the Resource's default Version attributes.
- REQUIRED in responses, OPTIONAL in requests.
- OPTIONAL in document view.
- MUST be a read-only attribute in API view.
- - MUST be an absolute URL to the Resource's `meta` sub-object.
+ - MUST be an absolute URL to the Resource's `meta` sub-object, except when
+ `?compact` is enabled and the meta sub-object is inlined, in which case
+ it MUST be a relative URL.
- Examples:
- `https://example.com/endpoints/ep1/messages/msg1/meta`
@@ -3922,7 +3955,7 @@ Content-Type: STRING ?
xRegistry-RESOURCEid: STRING # ID of Resource, not default Version
xRegistry-versionid: STRING # ID of the default Version
xRegistry-self: URL # Resource URL, not default Version
-xRegistry-xid: URL # Relative Resource URL
+xRegistry-xid: URI # Relative Resource URI
xRegistry-epoch: UINT # Start default Version's attributes
xRegistry-name: STRING ?
xRegistry-isdefault: true ?
@@ -3948,7 +3981,7 @@ Where:
- The `versionid` attribute MUST be the ID of the Resource's default Version.
- The `self` URL references the Resource, not the default Version.
- The `shortself` URL, if present, MUST be an alternative URL for `self`.
-- The `xid` URL references the Resource, not the default Version.
+- The `xid` URI references the Resource, not the default Version.
- The serialization of the `labels` attribute is split into separate HTTP
headers (one per label name).
- The `versionsurl` and `versionscount` Collection attributes are included,
@@ -4051,37 +4084,82 @@ be done in the other - running the risk of them getting out of sync.
The second, and better, option is to create a cross-reference from one
(the "source" Resource) to the other ("target" Resource). This is done
by setting the `xref` attribute on the source Resource to be the `xid`
-of the target Resource. For example, a source Resource's `meta` sub-object
-defined as:
+of the target Resource.
+
+The `xref` attribute is defined in the model as:
+
+```yaml
+"xref": {
+ "name": "xref",
+ "type": "relation",
+ "target": "/GROUPS/RESOURCES"
+}
+```
+
+where `/GROUPS/RESOURCES` will be the actual Group and Resource plural names
+of this Resource.
+
+Looking at a specific example, a Group/Resource model definition of:
```yaml
{
- # Resource URL: http://example.com/groups/group1/resource/sourceresource
- "RESOURCEid": "sourceresource",
- "xref": "/groups/group2/resources/targetresource"
+ "groups" : {
+ "schemagroups": {
+ "plural": "schemagroups",
+ "singular": "schemagroup",
+
+ "resources": {
+ "plural": "schemas",
+ "singular": "schema",
+ "attributes": {
+ "xref": {
+ "name": "xref",
+ "type": "relation",
+ "target": "/schemagroups/schemas"
+ }
+ }
+ }
+ }
+ }
}
```
-means that this "sourceresource" references the "targetresource" from
-"group2". When the source Resource is serialized (e.g. as a result of a
-`GET`), then all of the target Resource's attributes (except its `RESOURCEid`)
-will appear as if they were locally defined. So, if the target Resource was
-defined as:
+Means that `schemas` can be cross-referenced to other `/schemagroups/schema`
+Resource. Notice that `target` is a `xid` template to itself.
+
+For example: a `schema` Resource instance defined as (HTTP body of
+`PUT /schemagroups/group1/schemas/mySchema$details`):
```yaml
{
- "resourceid": "targetresource",
+ "schemaid": "mySchema",
+ "meta": {
+ "xref": "/schemagroups/group2/schemas/sharedSchema"
+ }
+}
+```
+
+means that `mySchema` references `sharedSchema`, which exists in `group2`.
+When this source Resource (`mySchema`) is retrieved, all of the target
+Resource's attributes (except its `RESOURCEid`) will appear as if they were
+locally defined.
+
+So, if the target Resource (`sharedSchema`) is defined as:
+
+```yaml
+{
+ "resourceid": "sharedSchema",
"versionid": "v1",
- "self": "http://example.com/groups/group2/resources/targetresource",
- "xid": "/groups/group2/resources/targetresource",
+ "self": "http://example.com/schemagroups/group2/schemas/sharedSchema",
+ "xid": "/schemagroups/group2/schemas/sharedSchema",
"epoch": 2,
"isdefault": true,
"createdat": "2024-01-01-T12:00:00",
"modifiedat": "2024-01-01-T12:01:00",
- "metaurl": "http://example.com/groups/groups2/resource/targetresource/meta",
+ "metaurl": "http://example.com/schemagroups/group2/schemas/sharedSchema/meta",
"versionscount": 1,
- "versionsurl": "http://example.com/groups/group2/resources/targetresource/versions"
+ "versionsurl": "http://example.com/schemagroups/group2/schemas/sharedSchema/versions"
}
```
@@ -4089,51 +4167,50 @@ then the resulting serialization of the source Resource would be:
```yaml
{
- "resourceid": "sourceresource",
+ "resourceid": "mySchema",
"versionid": "v1",
- "self": "http://example.com/groups/group1/resources/sourceresource",
- "xid": "/groups/group1/resources/sourceresource",
+ "self": "http://example.com/schemagroups/group1/schemas/mySchema",
+ "xid": "/schemagroups/group1/schemas/mySchema",
"epoch": 2,
"isdefault": true,
"createdat": "2024-01-01-T12:00:00",
"modifiedat": "2024-01-01-T12:01:00",
- "metaurl": "http://example.com/groups/group1/resource/sourceresource/meta",
+ "metaurl": "http://example.com/schemagroups/group1/schemas/mySchema/meta",
"meta": {
- "resourceid": "sourceresource",
- "self": "http://example.com/groups/groups2/resource/sourceresource/meta",
- "xid": "/groups/groups2/resource/sourceresource/meta",
- "xref": "/groups/group2/resources/targetresource",
+ "resourceid": "mySchema",
+ "self": "http://example.com/schemagroups/group1/schemas/mySchema/meta",
+ "xid": "/schemagroups/group1/schemas/mySchema/meta",
+ "xref": "/schemagroups/group2/schemas/sharedSchema",
"createdat": "2024-01-01-T12:00:00",
"modifiedat": "2024-01-01-T12:01:00"
},
"versionscount": 1,
- "versionsurl": "http://example.com/groups/group1/resources/sourceresource/versions"
+ "versionsurl": "http://example.com/schemagroups/group1/schemas/mySchema/versions"
}
```
Note:
-- The `RESOURCEid` of the source Resource MAY be different from the
- `RESOURCEid` of the target Resource.
-- The `xref` attribute MUST appear within the `meta` sub-object so a client
- can easily determine that this Resource is a cross-referenced Resource, and
- provide a URL to that targeted Resource (if ever needed).
-- All calculated attributes (such as the `defaultversionurl` and `versionsurl`)
- MUST use the `RESOURCEid` of the source Resource not the target Resource. In
+- Any attributes referencing the source MUST use the source's metadata. In
this respect, users of this serialization would never know that this is a
cross-referenced Resource except for the presence of the `xref` attribute.
-- The URL of the target Resource MUST be the `xid` of the target Resource, and
- be of the form: `/GROUPS/gID/RESOURCES/rID`, and MUST reference a Resource
- within the same Registry. However, it MUST NOT point to itself.
+ For example, its `RESOURCEid` MUST be the source's `id` and not the target's.
+- The `xref` attribute MUST appear within the `meta` sub-object so a client
+ can easily determine that this Resource is a cross-referenced Resource, and
+ it provides a reference to the targeted Resource.
+- The `xref` URL MUST be the `xid` of the target Resource.
From a consumption (read) perspective, aside from the presence of the `xref`
attribute, the Resource appears to be a normal Resource that exists within
`group1`. All of the specification defined features (e.g. `?inline`,
`?filter`) MAY be used when retrieving the Resource.
-However, from a write perspective it is quite different. Depending on the
-state of the source Resource different rules apply - see the following
-text:
+However, from a write perspective it is quite different. In order to update
+the target Resource's attributes (or nested entities), a write operation MUST
+be done on the appropriate target Resource entity directly. Write
+operations on the source MAY be done, however the changes are limited to
+converting it from a "cross-reference" Resource back into a "normal"
+Resource. See the following for more information:
When converting a "normal" Resource into a cross-reference Resource (adding
an `xref` value), or creating a new Resource that will be a cross-reference
@@ -4168,19 +4245,15 @@ following MUST be adhered to:
This will ensure that the Resource's `epoch` value will never decrease as a
result of this operation. Note that going from a "normal" Resource to a
cross-reference Resource does not have this guarantee. If the target Resource
- no longer exists then `target_Resource_Epoch` can be treated as zero.
+ no longer exists then `target_Resource_Epoch` MUST be treated as zero.
- Aside from the processing rules specified above, the Resource's attributes
that might have existed prior to the Resource being converted from a
"normal" Resource into a cross-reference Resource MUST NOT be resurrected
with their old values.
- Any relationship with the target Resource MUST be deleted.
-In order to update the target Resource's attributes (or nested entities), a
-write operation MUST be done on the appropriate target Resource entity
-directly.
-
-If the target Resource itself is a cross reference Resource, then inlining
-of the target Resource's attributes MUST NOT be done when serializing the
+If the target Resource itself is a cross reference Resource, then including
+the target Resource's attributes MUST NOT be done when serializing the
source Resource. Recursive, or transitively, following of `xref` URLs it not
done.
@@ -4421,7 +4494,7 @@ Where:
- If there is only one Version created, then it MUST become the default
Version, and use of the `?setdefaultversionid` query parameter is OPTIONAL.
- If there is more than one Version created, then use of the
- `setdefaultversionid` is RECOMMENDED.
+ `?setdefaultversionid` query parameter is RECOMMENDED.
- There MUST be at least one Version specified in the HTTP body. In other
words, an empty collection MUST generate an error since creating a Resource
with no Versions would immediate delete that Resource.
@@ -4514,7 +4587,7 @@ Content-Type: STRING ?
xRegistry-RESOURCEid: STRING ?
xRegistry-versionid: STRING ?
xRegistry-self: URL
-xRegistry-xid: URL
+xRegistry-xid: URI
xRegistry-epoch: UINTEGER ?
xRegistry-name: STRING ?
xRegistry-isdefault: BOOLEAN ?
@@ -4757,7 +4830,7 @@ Content-Type: STRING ?
xRegistry-RESOURCEid: STRING
xRegistry-versionid: STRING
xRegistry-self: URL
-xRegistry-xid: URL
+xRegistry-xid: URI
xRegistry-epoch: UINT
xRegistry-name: STRING ?
xRegistry-description: STRING ?
@@ -4782,7 +4855,7 @@ Where:
- `self` MUST be a URL to the Resource, not to the default Version of the
Resource.
- `shortself`, if present, MUST be an alternative URL for `self`.
-- `xid` MUST be a relative URL to the Resource, not to the default Version of
+- `xid` MUST be a relative URI to the Resource, not to the default Version of
the Resource.
- If `RESOURCEurl` is present then it MUST have the same value as `Location`.
- If `Content-Location` is present then it MUST be a URL to the Version of the
@@ -4859,7 +4932,7 @@ Where:
- `self` is a URL to the Resource (with `$details`), not to the default
Version of the Resource.
- `shortself`, if present, MUST be an alternative URL for `self`.
-- `xid` is a relative URL to the Resource (without `$details`), not to the
+- `xid` is a relative URI to the Resource (without `$details`), not to the
default Version of the Resource.
- `RESOURCE`, or `RESOURCEbase64`, MUST only be included if requested via use
of the `?inline` feature and `RESOURCEurl` is not set.
@@ -4999,31 +5072,13 @@ as defined below:
- Type: String
- Description: An immutable unique identifier of the Version.
- Constraints:
- - MUST be a non-empty string consisting of [RFC3986 `unreserved`
- characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3)
- (ALPHA / DIGIT / "-" / "." / "_" / "~").
+ - See [SINGULARid](#singularid-id-attribute).
- MUST NOT use a value of `null` or `request` due to these being reserved
- for use by the `setdefaultversionid` operation.
- - MUST be case insensitive unique within the scope of the owning Resource.
- - This attribute MUST be treated as case sensitive for look-up purposes.
- This means that an HTTP URL request to an entity with the wrong case for its
- `versionid` MUST be treated as "not found".
- - In cases where the `versionid` is specified outside of the serialization
- of the Version (e.g. part of a request URL, or a map key), its
- presence within the serialization of the entity is OPTIONAL. However, if
- present, it MUST be the same as any other specification of the `versionid`
- outside of the entity, and it MUST be the same as the entity's existing
- `versionid` if one exists, otherwise an error MUST be generated.
- - MUST be immutable.
+ for use by the `?setdefaultversionid` feature.
- Examples:
- `1.0`
- `v2`
- `v3-rc`
-TODO reuse SINGULARid section instead of duplicating this
-
-Note, since `versionid` is immutable, in order to change its value a new
-Version would need to be created with the new `versionid` that is a deep-copy
-of the existing Version. Then the existing Version can be deleted.
##### `isdefault` Attribute
- Type: Boolean
@@ -5321,7 +5376,7 @@ Content-Type: STRING ?
xRegistry-RESOURCEid: STRING
xRegistry-versionid: STRING
xRegistry-self: URL
-xRegistry-xid: URL
+xRegistry-xid: URI
xRegistry-epoch: UINT
xRegistry-name: STRING ?
xRegistry-isdefault: BOOLEAN ?
@@ -5340,7 +5395,7 @@ Where:
- `versionid` MUST be the `SINGULARid` of the Version.
- `self` MUST be a URL to the Version, not to the owning Resource.
- `shortself` MUST be an alternative URL for `self`.
-- `xid` MUST be a relative URL to the Version, not to the owning Resource.
+- `xid` MUST be a relative URI to the Version, not to the owning Resource.
- `Content-Disposition` SHOULD be present and if so, MUST be the `RESOURCEid`
value. This allows for HTTP tooling that is not aware of xRegistry to know
the desired filename to use if the HTTP body were to be written to a file.
@@ -5353,7 +5408,7 @@ Content-Type: STRING ?
xRegistry-RESOURCEid: STRING
xRegistry-versionid: STRING
xRegistry-self: URL
-xRegistry-xid: URL
+xRegistry-xid: URI
xRegistry-epoch: UINT
xRegistry-name: STRING ?
xRegistry-isdefault: BOOLEAN ?
@@ -5440,7 +5495,7 @@ Where:
- `versionid` MUST be the `SINGULARid` of the Version.
- `self` MUST be a URL to the Version, not to the owning Resource.
- `shortself` MUST be an alternative URL for `self`.
-- `xid` MUST be a relative URL to the Version, not to the owning Resource.
+- `xid` MUST be a relative URI to the Version, not to the owning Resource.
**Examples:**
@@ -5476,7 +5531,7 @@ To delete one or more Versions of a Resource, an HTTP `DELETE` MAY be used:
The processing of these two APIs is defined in the [Deleting Entities in a
Registry Collection](#deleting-entities-in-a-registry-collection)
-section. For more information about the `setdefaultversionid` query
+section. For more information about the `?setdefaultversionid` query
parameter see the [Default Version of a
Resource](#default-version-of-a-resource) section.
@@ -5806,12 +5861,16 @@ MUST be modified to do the following:
- Remove the default Version attributes from a Resource's serialization.
- When a Resource (source) uses the `xref` feature, the target Resource's
attributes are excluded from the source's serialization.
+- Convert the following attributes into relative URLs if the entities that
+ they reference are included in the response output:
+ `self`, `COLLECTIONSurl`, `metaurl`, `defaultversionurl`.
This is useful when a client wants to minimize the amount of data returned by
a server because the duplication of that data (typically used for human
-readability purposes) isn't necessary. For example, if tooling would ignore
+readability purposes) isn't necessary. For example, if tooling would ignore
the duplication, or if the data will be used to populate a new Registry, then
-this feature might be used.
+this feature might be used. It also makes the output more of a "stand-alone"
+document that minimizes external references.
For clarity, the serialization of a Resource when "compact" is used will
adhere to the following:
@@ -5828,7 +5887,7 @@ adhere to the following:
"RESOURCEid": "STRING",
"self": URL",
"shortself": "URL", ?
- "xid": "URL",
+ "xid": "URI",
"xref": "URL" ?
# Remaining attributes are absent if 'xref' is set
"epoch": UINTEGER",
diff --git a/message/spec.md b/message/spec.md
index 9ebb37e..e8fd039 100644
--- a/message/spec.md
+++ b/message/spec.md
@@ -79,6 +79,13 @@ this form:
"createdat": "TIMESTAMP",
"modifiedat": "TIMESTAMP",
+ "deprecated": {
+ "effective": "TIMESTAMP", ?
+ "removal": "TIMESTAMP", ?
+ "alternative": "URL", ?
+ "docs": "URL"?
+ }, ?
+
"basemessageurl": "URL", ? # Message being extended
"envelope": "STRING", ? # e.g. CloudEvents/1.0
@@ -238,6 +245,50 @@ The following extensions are defined for the `message` Resource in addition to
the core xRegistry Resource
[attributes](../core/spec.md#attributes-and-extensions):
+#### `deprecated`
+
+- Type: Object containing the following properties:
+ - `effective`
+ An OPTIONAL property indicating the time when the message entered, or will
+ enter, a deprecated state. The date MAY be in the past or future. If this
+ property is not present the message is already in a deprecated state.
+ If present, this MUST be an [RFC3339][rfc3339] timestamp.
+
+ - `removal`
+ An OPTIONAL property indicating the time when the message MAY be removed.
+ The message MUST NOT be removed before this time. If this property is not
+ present then client can not make any assumption as to when the message
+ might be removed. Note: as with most properties, this property is mutable.
+ If present, this MUST be an [RFC3339][rfc3339] timestamp and MUST NOT be
+ sooner than the `effective` time if present.
+
+ - `alternative`
+ An OPTIONAL property specifying the URL to an alternative message the
+ client can consider as a replacement for this message. There is no
+ guarantee that the referenced message is an exact replacement, rather the
+ client is expected to investigate the message to determine if it is
+ appropriate.
+
+ - `docs`
+ An OPTIONAL property specifying the URL to additional information about
+ the deprecation of the message. This specification does not mandate any
+ particular format or information, however some possibilities include:
+ reasons for the deprecation or additional information about likely
+ alternative message. The URL MUST support an HTTP GET request.
+
+ Note that an implementation is not mandated to use this attribute in
+ advance of removing an message, but is it RECOMMENDED that they do so.
+- Constraints:
+ - OPTIONAL
+- Examples:
+ - `"deprecated": {}`
+ - ```
+ "deprecated": {
+ "removal": "2030-12-19T00:00:00-00:00",
+ "alternative": "https://example.com/messages/popped"
+ }
+ ```
+
#### `basemessageurl`
- Type: URI-reference
diff --git a/schema/spec.md b/schema/spec.md
index cd20c37..5f8bb2a 100644
--- a/schema/spec.md
+++ b/schema/spec.md
@@ -71,6 +71,13 @@ this form:
"createdat": "TIMESTAMP",
"modifiedat": "TIMESTAMP",
+ "deprecated": {
+ "effective": "TIMESTAMP", ?
+ "removal": "TIMESTAMP", ?
+ "alternative": "URL", ?
+ "docs": "URL"?
+ }, ?
+
"format": "STRING", ?
"schemaurl": "URL", ?
@@ -294,6 +301,50 @@ the core xRegistry Resource
- MUST be a Resource level attribute defined within the `metaattributes`
section of the model.
+#### `deprecated`
+
+- Type: Object containing the following properties:
+ - `effective`
+ An OPTIONAL property indicating the time when the schema entered, or will
+ enter, a deprecated state. The date MAY be in the past or future. If this
+ property is not present the schema is already in a deprecated state.
+ If present, this MUST be an [RFC3339][rfc3339] timestamp.
+
+ - `removal`
+ An OPTIONAL property indicating the time when the schema MAY be removed.
+ The schema MUST NOT be removed before this time. If this property is not
+ present then client can not make any assumption as to when the schema
+ might be removed. Note: as with most properties, this property is mutable.
+ If present, this MUST be an [RFC3339][rfc3339] timestamp and MUST NOT be
+ sooner than the `effective` time if present.
+
+ - `alternative`
+ An OPTIONAL property specifying the URL to an alternative schema the
+ client can consider as a replacement for this schema. There is no
+ guarantee that the referenced schema is an exact replacement, rather the
+ client is expected to investigate the schema to determine if it is
+ appropriate.
+
+ - `docs`
+ An OPTIONAL property specifying the URL to additional information about
+ the deprecation of the schema. This specification does not mandate any
+ particular format or information, however some possibilities include:
+ reasons for the deprecation or additional information about likely
+ alternative schema. The URL MUST support an HTTP GET request.
+
+ Note that an implementation is not mandated to use this attribute in
+ advance of removing an schema, but is it RECOMMENDED that they do so.
+- Constraints:
+ - OPTIONAL
+- Examples:
+ - `"deprecated": {}`
+ - ```
+ "deprecated": {
+ "removal": "2030-12-19T00:00:00-00:00",
+ "alternative": "https://example.com/schema/myschema"
+ }
+ ```
+
#### `format`
- Type: String
diff --git a/tools/dict b/tools/dict
index c40a0b7..d61912a 100644
--- a/tools/dict
+++ b/tools/dict
@@ -112,6 +112,7 @@ metaschema
metaschemas
metaurl
middleware
+modelversion
modifiedat
modifiedby
monotomically
@@ -189,6 +190,7 @@ serverrequired
setdefaultversionid
setdefaultversionsticky
setversionid
+sharedschema
shortself
shorturl
siblingattributes