reduce scope of model changes allowed

Signed-off-by: Doug Davis <[email protected]>

core/spec.md

@@ -301,12 +301,19 @@ When HTTP query parameters are discussed, they are presented as `?NAME` where
 `NAME` is the name of the query parameter.
 
 Use of the words `GROUP` and `RESOURCE` are meant to represent the singular
-form of a Group and Resource type being used. While `GROUPS` and `RESOURCES`
-are the plural form of those respective types. Use of the word `SINGULAR`
-represents the singular form of the entity being referenced.
+name of a Group and Resource type being used. While `GROUPS` and `RESOURCES`
+are the plural name of those respective types. Use of the word `SINGULAR`
+represents the singular name of the entity being referenced. For example,
+for a "schema document" Resource type where its plural name is defined as
+`schemas` and its singular name is defined as `schema`, the `SINGULAR`
+value would be `schema`.
 
 Use of acronyms and words in all capital letters (e.g. `KEY`) typically
 represent a field that will be replaced by its real value at runtime.
+Additionally, the following acronyms are defined:
+- `gID` is the `SINGULARid` of a single Group.
+- `rID` is the `SINGULARid` of a single Resource.
+- `vID` is the `versionid` of a single Version of a Resource.
 
 The following are used to denote an instance of one of the associated data
 types (see [Attributes and Extensions](#attributes-and-extensions) for more
@@ -838,6 +845,9 @@ of the existing entity. Then the existing entity would be deleted.
 
 - Constraints:
   - MUST be a [RFC3339](https://tools.ietf.org/html/rfc3339) timestamp.
+  - This specification places no restrictions on the value of this attribute,
+    nor on its value relative to its `modifiedat` value or the current
+    date/time.  Implementations MAY choose restrict its values if necessary.
   - If present in a write operation request, the value MUST override any
     existing value, however a value of `null` MUST use the current date/time
     as the new value.
@@ -861,6 +871,9 @@ of the existing entity. Then the existing entity would be deleted.
 - Constraints:
   - MUST be a [RFC3339](https://tools.ietf.org/html/rfc3339) timestamp
     representing the time when the entity was last updated.
+  - This specification places no restrictions on the value of this attribute,
+    nor on its value relative to its `createdat` value or the current
+    date/time.  Implementations MAY choose restrict its values if necessary.
   - Any update operation (even one that does not change any attribute, such as
     a `PATCH` with no attributes provided), MUST update this attribute. This
     then acts like a `touch` type of operation.
@@ -903,17 +916,6 @@ This specification defines the following API patterns:
 /GROUPS/gID/RESOURCES/rID/versions/vID          # Access a Version of a Resource
 ```
 
-Where:
-- `GROUPS` is a Group type name (plural). e.g. `endpoints`.
-- `GROUP`, not shown, is the singular name of a Group type.
-- `gID` is the `SINGULARid` of a single Group.
-- `RESOURCES` is a Resource type name (plural). e.g. `messages`.
-- `RESOURCE`, not shown, is the singular name of a Resource type.
-- `rID` is the `SINGULARid` of a single Resource.
-- `vID` is the `versionid` of a single Version of a Resource.
-
-These acronym definitions apply to the remainder of this specification.
-
 While these APIs are shown to be at the root path of a Registry Service,
 implementation MAY choose to prefix them as necessary. However, the same
 prefix MUST be used consistently for all APIs in the same Registry instance.
@@ -2044,14 +2046,12 @@ with respect to how models are defined or updated:
   this aspect changed to `false`.
 - Specification defined attributes that are `readonly` and `serverrequired`
   MUST NOT have the `readonly` aspect changed to `false`.
-- Once an attribute is defined (per the specification or as an extension), the
-  `name` and `type` aspects of the attribute MUST NOT be changed.
 
-Changes to specification defined attributes MAY be included in the request.
+Changes to specification defined attributes MAY be included in the model.
 Any specification attributes not included in the request MUST be included in
 the resulting model. In other words, the Registry's model consists of the
 specification defined attributes overlaid with the attributes that are
-explicitly defined as part of an update request.
+explicitly defined as part of a model create/update request.
 
 Note: there is no mechanism defined to delete specification defined attributes
 from the model.
@@ -2061,45 +2061,31 @@ new attributes within the model definitions themselves), but only if
 the server supports them. Servers MUST reject model definitions that include
 unknown model language attributes.
 
-Once a Registry has been created, implementations MAY choose to limit the
-types of changes made to the model - for example, to ensure backwards
-compatibility of clients or to ensure existing entities do not need to be
-changed to be consistent with the new model.
-
-Implementations are REQUIRED to ensure that after any model changes are made,
-all of the entities in the Registry are valid with respect to the new model
-definition (including all Versions of Resources). How this is achieved will
-be implementation specific. For example, implementations can choose to
-automatically modify existing entities, or even to delete non-conforming
-entities (such as when Groups or Resource types are removed). However, it is
-STRONGLY RECOMMENDED that implementations not delete entities due to attribute
-modifications.
-
-When model changes are made, it might be necessary to modify existing entity's
-attributes to ensure they are conformant with the new model. The following
-ordered suggestions are defined to provide consistency across implementations,
-but it is NOT REQUIRED for implementations to follow these rules if a
-different set of changes are more appropriate:
-- If a `default` value is defined for the attribute, then it SHOULD be used.
-- If the attribute is OPTIONAL, then the attribute SHOULD be deleted.
-- If an enum is defined and `strict` is `true`, the first `enum` value SHOULD
-  be used.
-- If valid, the zero value for the attribute's type SHOULD be used:
-  - Array, Map, Object: empty value (e.g. `[]`, `{}`, `{}` respectively).
-  - Boolean: false.
-  - Numeric: zero.
-  - String, any of the URI/URL variants: empty string (`""`).
-  - 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.
+Once a Registry has been created, changes to the model are limited to:
+- Adding new Groups or Resources.
+- Adding new OPTIONAL attributes.
+
+Any model change that might result in existing data within the Registry
+becoming non-compliant MUST generate an error, even if it does not do so. For
+example, the following non-exhaustive list of changes MUST generate an error:
+- Deleting an attribute, Group or Resource.
+- Changing the `name` or `type` of an attribute.
+- Removing a value from the enumeration list of an attribute.
+- Enabling/disabling a feature that might impact storing data
+  (e.g. `hasdocument`).
+
+Some example changes that are allowed:
+- Changing the `description` of an attribute.
+- Adding an enumeration value to an attribute.
+- Changing the `readonly` aspect or `default` value of an attribute.
+
+Implementations MAY choose to limit the types of changes made to the model,
+or not support model updates at all.
+
+Breaking model changes would need be done by creating a new Registry instance
+(with the new model), and then an export/import of the data would need to be
+performed. Or by creating new Groups/Resources and migrating the data from the
+old ones to the new ones.
 
 The xRegistry schema for an empty Registry can be found [here](./model.json),
 while a schema for a sample xRegistry (with Groups and Resources) can be
@@ -2852,12 +2838,11 @@ Content-Type: application/json; charset=utf-8
 Where:
 - The HTTP body MUST contain all of the attributes, Groups and Resources that
   the client wishes to define.
-- Group and Resource types that are not present in the request MUST be
-  interpreted as a request to delete them and all entities of those types MUST
-  be deleted.
-- Attributes not present in the request MUST be interpreted as a request to
-  delete the attribute, and if the attribute is a specification defined
-  attribute then it MUST be added back with its default definition.
+- Specification defined attributes not included in the request MUST be added
+  by the server with their default definitions.
+
+See [Registry Model](#registry-model) for more details about the list of
+allowable changes to a model.
 
 A successful response MUST include a full representation of the Registry model
 and be of the form: