Manage Snapshot Tagging

[brian-ruf-ezd]

trafficstars

Description

As a developer issuing OSCAL REST API calls to manage snapshots, I want snapshots to be tagged with certain information, and I want to be able to manage that information.

Specifically, I want snapshots to include properties in the metadata (metadata/props) to address:

• Snapshot Time Stamp: Required timestamp indicating when the snapshot was created. There is no mechanism for setting this. It is assigned automatically by the implementation at the time the snapshot is created.
• Snapshot Description: Optional user-assigned description of the snapshot.
• Snapshot Type: Indicates the type of snapshot, such as to represent a formal, published version of the OSCAL content or an informal working copy, as well as to indicate whether the snapshot was automatically or manually created. There may be more than one.
• Snapshot Label: Optional user-assigned label for the snapshot. There may be more than one.

I want to be able to provide this information when creating a snapshot and manage it after the snapshot is created.

Acceptance Criteria

Expand the REST specification to include the following:

• Update GET /{model-name}/{id}/snapshot as follows:

  • [ ] The return content list items must include a snapshot node as defined below
  • [x] The summary and description for GET /{model-name}/{id}/snapshot is also updated as described in issue #88

• Update POST /{model-name}/{id}/snapshot as follows:

  • [ ] The summary is revised to say, "Creates a snapshot of the file in its current state."
  • [ ] The description is revised with the content shown below.
  • [ ] This payload allows JSON as defined below.
  • [ ] The method return content is updated as follows:
    • [ ] Change the top level node name from {model-name}-list to {model-name}-snapshot-list, which is the same as GET. The only difference is that this should always have exactly one item in the list and GET can have 0 or more elements in the list.
    • [ ] to include a "snapshot" node as described below.

• [ ] Add PUT /{model-name}/{id}/snapshot/{id} to the specification

  • [ ] The summary should say, "Modifies the snapshot description, types and labels."
  • [ ] The description should be included as shown below.
  • [ ] The payload allows JSON as described below.
  • [ ] The method returns the following status codes (consistent with other PUT methods):
    • [ ] 204 Successful update
    • [ ] 400, 401, 403, 404, 409, 410, 415, 422

Description Content

Description for POST /{model-name}/{id}/snapshot

Creates a snapshot of the file in its current state. The implementation _must_ assign and track a unique identifier for the snapshot, by which the snapshot may be referenced later. The implementation _must_ add the `snapshot-created` property to the OSCAL document's `metadata` as follows:

- **Snapshot Created** Property [**Exactly 1 (REQUIRED)**]: 
  - `"name" : "snapshot-created"`
  - `"value" : "2024-03-24T16:10:42.251Z"` (date-time-with-timezone)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

The implementation _may_ add a `snapshot-description` property, as well as `snapshot-label` and `snapshot-type` properties to the OSCAL document's `metadata` as follows when included in the payload from the client: 

- **Snapshot Description** Property [**0 or 1 (OPTIONAL)**]: 
  - `"name" : "snapshot-description"`
  - `"value" : "na"` (`value` is required by OSCAL, but not needed for this property. It can include any string.)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`
  - `"remarks" : "An optional snapshot description."` (markup-multiline)

- **Snapshot Label** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-label"`
  - `"value" : "v1.2.3"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

- **Snapshot Type** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-type"`
  - `"value" : "published"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

All of the above properties are OSCAL extensions and must include the namespace (`ns`) information.

Description for PUT /{model-name}/{id}/snapshot/{id}

Modifies the snapshot description, as well as the snapshot type and label tags. The implementation _must_ ensure the `snapshot-created` property is immutable.  The following properties may be added, changed, or removed by this method. 

- **Snapshot Description** Property [**0 or 1 (OPTIONAL)**]: 
  - `"name" : "snapshot-description"`
  - `"value" : "na"` (Value is required by OSCAL, but not needed for this property. It can include any string.)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`
  - `"remarks" : "An optional snapshot description."` (markup-multiline)

- **Snapshot Label** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-label"`
  - `"value" : "v1.2.3"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

- **Snapshot Type** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-type"`
  - `"value" : "published"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

All of the above properties are OSCAL extensions and must include the namespace (`ns`) information.

Payload

The payload for POST /{model-name}/{id}/snapshot and PUT /{model-name}/{id}/snapshot/{id}` is specified as follows:

{
    "snapshot" : {
    	"description" : "markup-multiline",
    	"labels": ["token"],
    	"types" : ["token"]
	}
}

• labels have a cardinality of 0 or more
• types have a cardinality of 0 or more
• description has a cardinality of 0 or 1

Return Content

Each list item in the {model-name}-snapshot-list JSON object must be expanded to include a snapshot node with the following child-nodes:

• [ ] "created" field (date-time-with-timezone) cardinality of exactly 1
• [ ] "description" field (markup-multiline) cardinality of 0 or 1
• [ ] "types" array of tokens with cardinality of 0 or more
• [ ] "labels" array of tokens with cardinality of 0 or more

{
  "{mode-name}-snapshot-list": [
    {
      "file-id": "BDDd1907-b362-5B1E-Bb0a-6E88CC4Bd6Bd",
      "title": "string",
      "published": "2024-03-24T16:10:42.251Z",
      "last-modified": "2024-03-24T16:10:42.251Z",
      "version": "Rv;XFD:(`%n&.EuD6/.& 09Y[B6>$'3d:0",
      "oscal-version": "{",
      "document-ids": {
        "document-ids": [
          {
            "document-id": {
              "scheme": "asGkkAK6e1wzlYsqYe8XshSdhF4Mwzmaxov-J4pc53DpP5LiDB-Pfdcn9Ki7AdUmd.IeHl9tKKypZOKJNjURt559ut4KexB:0K/:('*fXiU-%4Mb",
              "identifier": "string"
            }
          }
        ]
      },
      "markings": [
        "string"
      ],
      "status": "string",
      "remarks": "string",

     "comment" : "-------------------------------------------------------------------------------- (remove this)",

      "snapshot" : {
         "created" : "2024-03-24T16:10:42.251Z",
         "description" : "markup-multiline",
         "labels": ["token"],
         "types" : ["token"]
	},

     "comment" : "-------------------------------------------------------------------------------- (remove this)",

    }
  ]
}

[brian-ruf-ezd]

Note: Although the Swagger editor sometimes marks it as a syntax error, OpenAPI 3.x allows markup in description fields. When expressing markup in YAML, the OpenAPI spec requires the pipe character to start, with the rest of the markup following on the next line indented. This article explains it: https://www.baeldung.com/swagger-format-descriptions This was used in the info description.

Example:

      description: | 
        Returns *every* relevant **assessment** plan.

        ```
        test
        ```

        Another line on the writeup.

[brian-ruf-ezd]

~80% complete. Had to handle linting issues in the pipeline. Expect to complete remaining 20% plus testing in sprint 68.

[brian-ruf-ezd]

Reviewed 2024-05-22. LGTM