diff --git a/source/extension/jsonpatch/context.json b/source/extension/jsonpatch/context.json new file mode 100644 index 000000000..1a5fccbc4 --- /dev/null +++ b/source/extension/jsonpatch/context.json @@ -0,0 +1,3 @@ +JSONPatch +operations => (json literal????) +patchTarget \ No newline at end of file diff --git a/source/extension/jsonpatch/index.md b/source/extension/jsonpatch/index.md new file mode 100644 index 000000000..cb97e7b4f --- /dev/null +++ b/source/extension/jsonpatch/index.md @@ -0,0 +1,155 @@ + + + +### Modifying resource properties + +Many Scene interaction use cases can be accomplished using the `enables` and `disables` properties to toggle the `"behavior": ["hidden"]`, and/or using activating annotations with bodies that can be _activated_: the examples above show a Camera and then an Animation being activated. Models in the Scene can also be shown and hidden via these properties. + +> when to use enables and when to use the `body` of the activating anno - are they equivalent for, say, a hidden model: enable it, activate it - interchangeable? + +For some interactions it is necessary to do more than show or hide or "activate" resources, by changing just `"behavior": ["hidden"]`. Other properties can also be changed via the [JSON Patch](link) mechanism. + +```jsonc +{ + "type": "JSONPatch", + "patchTarget": "https://example.org/iiif/scene1/scene-with-color-change", // the Scene + "operations": [ + { + "op": "replace", + "path": "/backgroundColor", // path to the property being changed. + "value": "#FF99AA" + } + ] +} +``` + + +> **This is a clear distinction like level0, level1 - a client can simply choose not to support arbitrary patching.** + +> Be clear that you still need to have all the patchable resources present from the start, you can't pull them in later. + +In the following simple example, the background color of the Scene is changed: + + +```jsonc +{ + "id": "https://example.org/iiif/3d/property-change.json", + "type": "Manifest", + "label": { "en": ["Whale Mandible"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/scene-with-color-change", + "type": "Scene", + "label": { "en": ["A Scene Containing a Whale Mandible"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-mandible", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", + "type": "Model" + }, + "target": "https://example.org/iiif/scene1/scene-with-color-change" + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/color-change-commenting-anno", + "type": "Annotation", + "motivation": ["commenting"], + "body": [ + { + "type": "TextualBody", + "value": "Change the background color" + } + ], + "target": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-mandible", // or the Scene? + "type": "Annotation" + } + ] + } + { + "id": "https://example.org/iiif/3d/color-change-activating-anno", + "type": "Annotation", + "motivation": ["activating"], + "target": [ + { + "id": "https://example.org/iiif/3d/color-change-commenting-anno", + "type": "Annotation" + } + ], + "body": [ + { + "type": "JSONPatch", + "patchTarget": "https://example.org/iiif/scene1/scene-with-color-change", + "operations": [ + { + "op": "replace", + "path": "/backgroundColor", + "value": "#FF99AA" + } + ] + } + ] + } + ] + } + ] + } + ] + } + ] +} +``` + + +# Classes + + +#### JSONPatch +{: #JSONPatch} + +TODO + + +# Properties + +### operations +{: operations} + +TODO + +(An array of JSONPatch operations as defined in that spec.) +Guard rails? + + + +### patchTarget +{: patchTarget} + +TODO - guard rails on patchTarget + + + + + +## Activating Annotations + +* If the body has the `type` "JSONPatch", apply the patch operations listed in `operations` to the resource identified by `patchTarget`. (see [ref]). + + +## Storytelling example + +* Something really cool that brings a lot of things together! +* Use JSONPatch to move a model too. \ No newline at end of file diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 3c936691e..2d7a29853 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -2012,7 +2012,6 @@ The `body` of the annotation is then activated. This has different processing re * if the annotation has the `behavior` "hidden", then remove "hidden" from the `behavior`. * if the annotation paints a Camera, make that Camera the active Camera (i.e., make this the viewport) (see [ref]). * If the body is a SpecificResource with a `selector` property with the type "AnimationSelector", play the animation named by the `value` property of the Selector. (see [ref]). -* If the body has the `type` "JSONPatch", apply the patch operations listed in `operations` to the resource identified by `patchTarget`. (see [ref]). * Processing for other body types can be found in the [IIIF Cookbook][ref] Activating annotations are provided in a Container's `annotations` property. They can be mixed in with the commenting (or other interactive annotations) they target, or they can be in a separate AnnotationPage. The client should evaluate all the activating annotations it can find. @@ -2394,117 +2393,6 @@ Camera when annotation selected: Camera for annotation -### Modifying resource properties - -Many Scene interaction use cases can be accomplished using the `enables` and `disables` properties to toggle the `"behavior": ["hidden"]`, and/or using activating annotations with bodies that can be _activated_: the examples above show a Camera and then an Animation being activated. Models in the Scene can also be shown and hidden via these properties. - -> when to use enables and when to use the `body` of the activating anno - are they equivalent for, say, a hidden model: enable it, activate it - interchangeable? - -For some interactions it is necessary to do more than show or hide or "activate" resources, by changing just `"behavior": ["hidden"]`. Other properties can also be changed via the [JSON Patch](link) mechanism. - -```jsonc -{ - "type": "JSONPatch", - "patchTarget": "https://example.org/iiif/scene1/scene-with-color-change", // the Scene - "operations": [ - { - "op": "replace", - "path": "/backgroundColor", // path to the property being changed. - "value": "#FF99AA" - } - ] -} -``` - -> **This is a clear distinction like level0, level1 - a client can simply choose not to support arbitrary patching.** - -> Be clear that you still need to have all the patchable resources present from the start, you can't pull them in later. - -In the following simple example, the background color of the Scene is changed: - - -```jsonc -{ - "id": "https://example.org/iiif/3d/property-change.json", - "type": "Manifest", - "label": { "en": ["Whale Mandible"] }, - "items": [ - { - "id": "https://example.org/iiif/scene1/scene-with-color-change", - "type": "Scene", - "label": { "en": ["A Scene Containing a Whale Mandible"] }, - "items": [ - { - "id": "https://example.org/iiif/scene1/page/p1/1", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/painting-anno-for-mandible", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", - "type": "Model" - }, - "target": "https://example.org/iiif/scene1/scene-with-color-change" - } - ], - "annotations": [ - { - "id": "https://example.org/iiif/scene1/page/activators", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/color-change-commenting-anno", - "type": "Annotation", - "motivation": ["commenting"], - "body": [ - { - "type": "TextualBody", - "value": "Change the background color" - } - ], - "target": [ - { - "id": "https://example.org/iiif/3d/painting-anno-for-mandible", // or the Scene? - "type": "Annotation" - } - ] - } - { - "id": "https://example.org/iiif/3d/color-change-activating-anno", - "type": "Annotation", - "motivation": ["activating"], - "target": [ - { - "id": "https://example.org/iiif/3d/color-change-commenting-anno", - "type": "Annotation" - } - ], - "body": [ - { - "type": "JSONPatch", - "patchTarget": "https://example.org/iiif/scene1/scene-with-color-change", - "operations": [ - { - "op": "replace", - "path": "/backgroundColor", - "value": "#FF99AA" - } - ] - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` - # Integration seeAlso, service(s), extensions @@ -2552,7 +2440,6 @@ Chaining together activating annotations can then allow the implementation of, a ## Storytelling example * Something really cool that brings a lot of things together! -* Use JSONPatch to move a model too. # Conveying Physical Dimensions diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 665ee2c35..71572a609 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1028,6 +1028,7 @@ An Agent _MAY_ have the following properties: [id](#id), [seeAlso](#seeAlso) and } ``` + #### Quantity {: #Quantity} @@ -1805,7 +1806,6 @@ The `body` of the annotation is then activated. This specification defines the f * if the annotation has the `behavior` "hidden", then remove "hidden" from the `behavior`. * if the annotation paints a Camera, make that Camera the active Camera (i.e., make this the viewport) (see [ref]). * If the body is a SpecificResource with a `selector` property with the type "AnimationSelector", play the animation named by the `value` property of the Selector. (see [ref]). -* If the body has the `type` "JSONPatch", apply the patch operations listed in `operations` to the resource identified by `patchTarget`. (see [ref]). ### navDate @@ -1912,6 +1912,7 @@ The value must be a JSON object, with the `id` and `type` properties. The value } ``` + ### partOf {: #partOf} @@ -1929,6 +1930,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and The resources referred to by the `accompanyingContainer` and `placeholderContainer` properties are `partOf` that referring Container. + ### placeholderContainer {: #placeholderContainer}