diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 8d74cc6..8f9dbaa 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -122,9 +122,17 @@ The result of the `target` JSONPath expression MUST be zero or more objects or a To update a primitive property value such as a string, the `target` expression should select the _containing_ object in the target document and `update` should contain an object with the property and its new primitive value. -Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced. +Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced with a `remove` action followed by an `update` or `copy` action. -The properties of the `update` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the `update` object are recursively merged with the properties in the target object with the same names; new properties are added to the target object. +The properties of the `update` or `copy` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the `update` object is merged with the target object by recursively applying these steps: + +- A property that only exists in the target object is left unchanged. +- A property that only exists in the `update` or `copy` object is inserted into the target object. +- If a property exists in both `update` or `copy` and target object: + - A primitive value of the `update` or `copy` property replaces a primitive value of the target property. + - An array value of the `update` or `copy` property is concatenated with an array value of the target property. + - An object value of the `update` or `copy` property is recursively merged with an object value of the target property. + - Other property value combinations are incompatible and result in an error. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -244,6 +252,21 @@ paths: responses: 200: description: OK + /items/{id}/subitems: + get: + x-oai-traits: ['paged'] + parameters: + - name: id + in: path + required: true + responses: + 200: + description: OK + /other: + get: + responses: + 200: + description: OK ``` With the above OpenAPI document, the following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied. @@ -254,7 +277,7 @@ info: title: Apply Traits version: 1.0.0 actions: - - target: $.paths.*.get[?@.x-oai-traits.paged] + - target: $.paths.*.get[?(@.x-oai-traits[?(@ == 'paged')])] update: parameters: - name: top @@ -265,6 +288,50 @@ actions: # ... ``` +resulting in + +```yaml +openapi: 3.1.0 +info: + title: API with a paged collection + version: 1.0.0 +paths: + /items: + get: + x-oai-traits: ["paged"] + responses: + 200: + description: OK + parameters: + - name: top + in: query + # ... + - name: skip + in: query + # ... + /items/{id}/subitems: + get: + x-oai-traits: ["paged"] + parameters: + - name: id + in: path + required: true + - name: top + in: query + # ... + - name: skip + in: query + # ... + responses: + 200: + description: OK + /other: + get: + responses: + 200: + description: OK +``` + This approach allows inversion of control as to where the Overlay updates apply to the target document itself. ### Specification Extensions