--- title: "Usage Scenarios" slug: "scenarios" updated: 2024-11-18T06:08:32Z published: 2024-11-18T06:08:32Z canonical: "docs.oscal.io/scenarios" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.oscal.io/llms.txt > Use this file to discover all available pages before exploring further. # Usage Scenarios ## Scenarios ### Scenario 1 #### [Using Content Identifiers](/docs/scenarios#scenario-1-using-content-identifiers) - Scenario 1A: [Initial Delivery of a Component Definition](/docs/scenarios#scenario-1a-initial-delivery-of-a-component-definition) - Scenario 1B: [Acquiring a Component Definition Using a Content Identifier](/docs/scenarios#scenario-1b-acquire-a-component-definition-using-a-content-identifier) - Scenario 1C: [Updating an Existing Component Definition](/docs/scenarios#scenario-1c-updating-an-existing-component-definition) - Scenario 1D: [Discovering and Acquiring Additional Component Definitions](/docs/scenarios#scenario-1d-discovering-and-acquiring-additional-component-definitions) ### Scenario 2 #### Using Attachments - Scenario 2A: [Delivering an SSP With Attachments](/docs/scenarios#scenario-2a-delivering-an-ssp-with-attachments) - Scenario 2B: [Adding a New Attachment to an SSP](/docs/scenarios#scenario-2b-adding-a-new-attachment-to-an-ssp) - Scenario 2C: [Acquiring an SSP With Attachments](/docs/scenarios#scenario-2c-acquiring-an-ssp-with-attachments) All scenarios use `https://example.com/v1` as the root URL for the server. --- ## Scenario 1: Using Content Identifiers **Client**: OSCAL-based Component Authoring Tool **Server**: OSCAL Content Registry [Content Identifiers](/v1/docs/content-identifiers) are crucial to the successful operation of an OSCAL REST OpenAPI implementation. This scenario walks through the lifecycle of content as it is first prepared and introduced into a repository, assigned a content identifier, later retrieved, modified, and re-submitted into the repository. Finally, this scenario will demonstrate how to search and acquire similar artifacts using the content identifier. POST a Component Definition [![](https://mermaid.ink/img/pako:eNqFkslOwzAQhl9lZBTlkkpNQRx8QGqSI1wocCDpwY0nraXEExwHWqq-O46rbmLzwcv83yz2eMtKksg4C4JtoQGUVpaD3wKEdoUNhhzChegwjM6tL8IosaixC4-4k1qjGmE2KdVkBr-r-HYyua4OrifiCdf2RFV-fKcSMhLNH9FqpfEkj_04kzssScuLgsZjEV-kqkjbmfrEEJw8uWnX4V7aDYubdkFQ6EJXNX2UK2Es3D8O5wGZ5vGUQ4a1ekcDAlJqWtKorbNVw0sq0nMYje4gyeOEw7R865XB38h90MQ7pHmccnhupbD_8KnnszzOXCmqK8nXouUx20--3ZxFrEHTCCVd830DC-YbWzDutkPDC-Zu7zjRW5ptdMm4NT1GzFC_XDFeibpzp97XmCmxNKI5WlEqS-Zh_7f8F4tYK_Qr0YHZfQHzm8Yo?type=png)](https://mermaid.live/edit#pako:eNqFkslOwzAQhl9lZBTlkkpNQRx8QGqSI1wocCDpwY0nraXEExwHWqq-O46rbmLzwcv83yz2eMtKksg4C4JtoQGUVpaD3wKEdoUNhhzChegwjM6tL8IosaixC4-4k1qjGmE2KdVkBr-r-HYyua4OrifiCdf2RFV-fKcSMhLNH9FqpfEkj_04kzssScuLgsZjEV-kqkjbmfrEEJw8uWnX4V7aDYubdkFQ6EJXNX2UK2Es3D8O5wGZ5vGUQ4a1ekcDAlJqWtKorbNVw0sq0nMYje4gyeOEw7R865XB38h90MQ7pHmccnhupbD_8KnnszzOXCmqK8nXouUx20--3ZxFrEHTCCVd830DC-YbWzDutkPDC-Zu7zjRW5ptdMm4NT1GzFC_XDFeibpzp97XmCmxNKI5WlEqS-Zh_7f8F4tYK_Qr0YHZfQHzm8Yo) ### Scenario 1A: Initial Delivery of a Component Definition A user creates an OSCAL component definition file in JSON for Keycloak and wishes to add it to the OSCAL Content Registry for the first time. POST a Component Definition [![](https://mermaid.ink/img/pako:eNqNU02P0zAQ_SuDUZUikrYp7B4i1APlsEKCXdHCAeXi2pPW1LGN7S7NrvrfsZN-bNlVhQ_-mPfmzWQy80iY5kgK0us9lgpAKOELaK8AiV9hjUkByYI6TNKn1h_UCrqQ6JIjPUDGipraZqqlttHvdX49Hr-rDq4nxhy3_sSq2vWc9VFbjvaCmhQKT_CoXU9gh0wrfjmhSis_Ew-YQIDH78026aBdPMK26_VKVSqHvzeoGH4SdGlp3XEsMg92ueiPUsiv8xTGV1dvOshQ6wUThioPUylQ-ef2Gdp7tFE9Ih0Lssnk7R4p4O52NoeV98YVwyFuaW0kDpiuh_f5MBxGq-CScazifxP6H6UgdVKijdSUF7DGhoXbOnvJf_DLXRK5mc_v4AYpjw_KGDoHXq_xf12modYxoG8MBgFjpGA0xh3GuB8WdtL_7vAM2NYStD0zNTTYRBVtVodOoR4H-6p3UWMNs302BXxDF77ThYDjUQ5Ti4HPX53zY8YH_rFSLxUok8J56FP5hzYOPs9uv-4jo-JdQ5GU1GhrKniYqnYyStJOTEmKcI2TVJLQVoFHN17PGsVI4e0GU2L1ZrkiRUWlC6-N4SHTfb8drciF1_ZLN7Tt7KYkNNNPrQ-c3V9UODou?type=png)](https://mermaid.live/edit#pako:eNqNU02P0zAQ_SuDUZUikrYp7B4i1APlsEKCXdHCAeXi2pPW1LGN7S7NrvrfsZN-bNlVhQ_-mPfmzWQy80iY5kgK0us9lgpAKOELaK8AiV9hjUkByYI6TNKn1h_UCrqQ6JIjPUDGipraZqqlttHvdX49Hr-rDq4nxhy3_sSq2vWc9VFbjvaCmhQKT_CoXU9gh0wrfjmhSis_Ew-YQIDH78026aBdPMK26_VKVSqHvzeoGH4SdGlp3XEsMg92ueiPUsiv8xTGV1dvOshQ6wUThioPUylQ-ef2Gdp7tFE9Ih0Lssnk7R4p4O52NoeV98YVwyFuaW0kDpiuh_f5MBxGq-CScazifxP6H6UgdVKijdSUF7DGhoXbOnvJf_DLXRK5mc_v4AYpjw_KGDoHXq_xf12modYxoG8MBgFjpGA0xh3GuB8WdtL_7vAM2NYStD0zNTTYRBVtVodOoR4H-6p3UWMNs302BXxDF77ThYDjUQ5Ti4HPX53zY8YH_rFSLxUok8J56FP5hzYOPs9uv-4jo-JdQ5GU1GhrKniYqnYyStJOTEmKcI2TVJLQVoFHN17PGsVI4e0GU2L1ZrkiRUWlC6-N4SHTfb8drciF1_ZLN7Tt7KYkNNNPrQ-c3V9UODou) 1. Client *optionally* inserts an *external identifier* into the metadata before sending it to the server. a. Client generates a v4 or v5 UUID and inserts it into the OSCAL content's `//metadata/document-ids` array using `http://oscal.io/oscal/identifier/externaluuid` for the `scheme` value. (This example is JSON; however, the OSCAL content may be XML, JSON or YAML, and the inserted document ID must match the native format of the content.) b. If the organization sends the same component definition to three different repositories, it should have the same external identifier in all three. c. The external identifier is tracked and managed by the sending organization. External Document Identifier Added (May be XML, JSON, or YAML) ``` "metadata": { "title" : "Keycloak Docker Image", "last-modified" : "2024-11-11T00:00:00Z", "oscal-version" : "1.1.2" "document-ids": [ { "identifier": "11111111-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/externaluuid" } ] } ``` *Partial Structure for Illustrative Purposes Only* 1. Client uses the REST POST method to send the Component Definition File to the OSCAL Content Registry. a. Client -> Server: `POST https://example.com/v1/component-definition` b. Payload: `my-component-definition.json` (may be XML, JSON, or YAML) c. HTTP Header: access token d. HTTP Header: `Content-type: application/json` (or `application/xml` or `application/yaml` as appropriate) 2. The OSCAL Content Registry receives and processes the file. a. The server verifies the access token has write access to the repository. b. The server verifies the content has valid syntax based on the content's declared OSCAL version (`oscal-version`). c. The server *optionally* stores a snapshot of the original content, exactly as it was received. d. The server checks for the existence of a content identifier and finds none. e. The server generates a v4 or v5 UUID and inserts it into the content's `//metadata/document-ids` array using `http://oscal.io/oscal/identifier/contentuuid` for the `scheme` value. f. The server stores the modified version of the file as the working version. Content Document Identifier Added (May be XML, JSON, or YAML) ``` "metadata": { "title" : "Keycloak Docker Image", "last-modified" : "2024-11-11T00:00:00Z", "oscal-version" : "1.1.2" "document-ids": [ { "identifier": "11111111-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/externaluuid" }, { "identifier": "22222222-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/contentuuid" } ], } ``` *Partial Structure for Illustrative Purposes Only* 1. The server responds to the client to indicate success and report the identifier to be used. a. Server -> Client: - Response: 201 Successfully created! - Payload: `component-definition-list` object in JSON with exactly one element in it. Content Document Identifier (May be XML, JSON, or YAML) ``` { "component-definition-list" : [ { "content-uuid": "22222222-3333-4000-8000-000000000001", "title" : "Keycloak Docker Image", "last-modified" : "2024-11-11T00:00:00Z", "oscal-version": "1.1.2", "document-ids": [ { "identifier": "11111111-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/externaluuid" }, { "identifier": "22222222-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/contentuuid" } ], "markings" : [], "remarks" : "" } ] } ``` --- ### Scenario 1B: Acquiring a Component Definition Using a Content Identifier This scenario addresses the use case where the user wishes to retrieve the Keycloak component definition from the registry in XML format for modification. GET a Component Definition [![](https://mermaid.ink/img/pako:eNqNU21v0zAQ_isnoyqtSJY2exGKUKVRJgZaYaIVApQvTnJprSW2cZypZep_55z0bSpM3AfH9vPcc-fL3RPLVI4sZr3eUyIBhBQ2hnYL4NklVujF4KW8Rs8_vv3GjeBpibW3pxOkjai4WU9UqYzzezW6iqLzYud6YMxxZQ-sorVT1jtlcjQvqJVC4gEetnYE15gpmb-cUKGknYnf6AHB0YVeeR20cR9aNr1eIhNZ468GZYbvBV8YXnUcg5kFs0j7Qx9GVyMfosvLQQdpbqzIhObSwqQUKO3p_QzNIxqn7pCOBcF4_HqLxPDhZg5La3UdhyGueKVLPMtUFT6OQvpoJckjyLFwv00oGUZbC87JgguqRvDGLcODjZ5Ho3D7aLfz-T3cIs_dgWcZ1jVY9YAS-qIAqSzoJi1FBlRVS96D_5S6JilNbcW1Jm_eZrqqyrepgXH_-_TOh0-zL5-Byxx-XE_vYPpxegPztcZ664r5ALpYnb4rUrCNG8NXrKkSNcYQDYfPaS6lHe2er0vF8xgecJ25XfC3Ep5RYv_WOH6WSz8cT7pSBJbSPXlhJ4T0LuazCk3FRU6z1s5Lwto5SlhMWzdfCaNmIx5vrJqtZcZiaxr0mVHNYsnigpc1nRqdc7vrwv0t5sIqM-1GuZ1on1GL_VRqx9n8AUebOK8?type=png)](https://mermaid.live/edit#pako:eNqNU21v0zAQ_isnoyqtSJY2exGKUKVRJgZaYaIVApQvTnJprSW2cZypZep_55z0bSpM3AfH9vPcc-fL3RPLVI4sZr3eUyIBhBQ2hnYL4NklVujF4KW8Rs8_vv3GjeBpibW3pxOkjai4WU9UqYzzezW6iqLzYud6YMxxZQ-sorVT1jtlcjQvqJVC4gEetnYE15gpmb-cUKGknYnf6AHB0YVeeR20cR9aNr1eIhNZ468GZYbvBV8YXnUcg5kFs0j7Qx9GVyMfosvLQQdpbqzIhObSwqQUKO3p_QzNIxqn7pCOBcF4_HqLxPDhZg5La3UdhyGueKVLPMtUFT6OQvpoJckjyLFwv00oGUZbC87JgguqRvDGLcODjZ5Ho3D7aLfz-T3cIs_dgWcZ1jVY9YAS-qIAqSzoJi1FBlRVS96D_5S6JilNbcW1Jm_eZrqqyrepgXH_-_TOh0-zL5-Byxx-XE_vYPpxegPztcZ664r5ALpYnb4rUrCNG8NXrKkSNcYQDYfPaS6lHe2er0vF8xgecJ25XfC3Ep5RYv_WOH6WSz8cT7pSBJbSPXlhJ4T0LuazCk3FRU6z1s5Lwto5SlhMWzdfCaNmIx5vrJqtZcZiaxr0mVHNYsnigpc1nRqdc7vrwv0t5sIqM-1GuZ1on1GL_VRqx9n8AUebOK8) 1. Client uses the `content-uuid` value returned in the JSON response of the Scenario 1A above to formulate a GET request. a. `GET https://example.com/v1/component-definition/22222222-3333-4000-8000-000000000001` b. HTTP Headers: - access token (not required if the content is publicly available) - HTTP Header: `Accept: application/xml` (See the [`GET /{model-name}/{content-uuid}`](/v1/docs/primary-endpoints#get-modelnamecontentuuid) for the list of accepted MIME types for each OSCAL format.) 2. The server uses the content UUID value and HTTP Accept Header to identify the requested content in the requested format. a. The server finds the OSCAL content in it's content repository using the content UUID value `22222222-3333-4000-8000-000000000001` that was assigned in 1A above. b. If the server does not have the requested OSCAL format available, it converts the content. - Each implementation is free to determine if they wish to convert to all formats upon receipt or convert upon request. - If converting upon request, the server should implement a 202 response with a URL that the client can use to monitor for completion. c. The server returns the requested OSCAL content in the requested format. - Response: 200 - Payload: keycloak-component.definition.xml - HTTP Header: `Content-type: application/xml` (May be `application/json` or `application/yaml` if either of those formats were requested.) --- ### Scenario 1C: Updating an Existing Component Definition After the client in 1B acquires the Keycloak component definition and makes modifications, it then must return the updated file to the server, and elects to use XML format. PUT a Component Definition [![](https://mermaid.ink/img/pako:eNqNU21v0zAQ_iuHUZVNJEubdROyUCUoHya0jokUBChf3PjaGhLb2M7UbOp_x07atWgwcR_89jx399i-eyCl4kgoGQweCgkgpHAUuiVA5NZYY0QhWjCLUXx8-oUZwRYV2uiR7iFtRM1MO1WVMsHv5egyy86Xe9cDY44bd2AtO3vKeqcMR_NMtEpIPMDDzo5gi6WS_HlBSyVdLu4xAg9nY72JemgbJj9sB4NCFtLirwZlie8FWxlW9xyDpQOzWpwMYxhdjmLILi5Oe0gz40QpNJMOppVA6Z6e52ju0IToAelZkEwmr3YIhdvPc1g7py1NU9ywWld4Vqo6vRulftJKeo-E4zJ8m1AyzXaWnHtLxv41ktdhGB5s9Gc2n-6QjbWVYpzC32KfbeoKTmashQXC19l1DB_yjzcxKAPf3s6uT_8d9mo-v4UrZDxsWFmiteDUT5T_6TL1PxS0uFajD6B1JUrWXddLom8WBtLJTtcx-MMqGdQdn7XMX6JP26cKz53sJFD4hNbf2_os2XAMedNpfQE3aq_BM1xjJPI-BkreV5HfkpjUaGomuO-mriMK0nVKQahfhg4qiC8nz2ONU3krS0KdaTAmRjWrNaFLVlm_azRnbl9nj6fIhVNm1jdr17Mx8UX0Xak9Z_sbsvwvHA?type=png)](https://mermaid.live/edit#pako:eNqNU21v0zAQ_iuHUZVNJEubdROyUCUoHya0jokUBChf3PjaGhLb2M7UbOp_x07atWgwcR_89jx399i-eyCl4kgoGQweCgkgpHAUuiVA5NZYY0QhWjCLUXx8-oUZwRYV2uiR7iFtRM1MO1WVMsHv5egyy86Xe9cDY44bd2AtO3vKeqcMR_NMtEpIPMDDzo5gi6WS_HlBSyVdLu4xAg9nY72JemgbJj9sB4NCFtLirwZlie8FWxlW9xyDpQOzWpwMYxhdjmLILi5Oe0gz40QpNJMOppVA6Z6e52ju0IToAelZkEwmr3YIhdvPc1g7py1NU9ywWld4Vqo6vRulftJKeo-E4zJ8m1AyzXaWnHtLxv41ktdhGB5s9Gc2n-6QjbWVYpzC32KfbeoKTmashQXC19l1DB_yjzcxKAPf3s6uT_8d9mo-v4UrZDxsWFmiteDUT5T_6TL1PxS0uFajD6B1JUrWXddLom8WBtLJTtcx-MMqGdQdn7XMX6JP26cKz53sJFD4hNbf2_os2XAMedNpfQE3aq_BM1xjJPI-BkreV5HfkpjUaGomuO-mriMK0nVKQahfhg4qiC8nz2ONU3krS0KdaTAmRjWrNaFLVlm_azRnbl9nj6fIhVNm1jdr17Mx8UX0Xak9Z_sbsvwvHA) 1. Client modified the content it retrieved in 1B above, and is ready to return the modified version to the server. 2. Client uses the REST PUT method to replace the Keycloak component definition file in the OSCAL Content Registry with the updated version. a. Client -> Server: `PUT https://example.com/v1/component-definition/22222222-3333-4000-8000-000000000001` b. Payload: `my-modified-component-definition.xml` (May be XML, JSON, or YAML) c. HTTP Header: access token d. HTTP Header: `Content-type: application/xml` (or `application/json` or `application/yaml` as appropriate) 3. The Server receives and processes the file. a. The server verifies the access token has write-access to the repository. b. The server verifies the content has valid syntax based on the content's declared OSCAL version (`oscal-version`). c. The server checks for the existence of the server's working copy of the content using the content identifier and finds it. d. The server *optionally* makes a snapshot of the server's working copy. e. The server replaces its working copy with the content received from the client. 4. The server responds to the client to indicate success and report the identifier to be used. a. Server -> Client: - Response: 204 Success! No Content Returned - Payload: *None* --- ### Scenario 1D: Discovering and Acquiring Additional Component Definitions A System Security Plan (SSP) author is searching for a Keycloak component definition to import into their SSP. Discovering and Acquiring Component Definitions The client queries for the list of component definitions [![](https://mermaid.ink/img/pako:eNp9U9uO0zAQ_ZXBqEoRKW0Duw9-WAkWxAoJdkUqHlBepvaktXDsYDulZdV_x056WVi0fvBlzpmLfcb3TFhJjLPR6L4yAMqowKHfAmRhTQ1lHLIlesryh9Zv6BQuNfnsRI9Q61SDbndttXXJ7_n8sihe10fXM2NB23Bm1f14zHpnnST3RDStDJ3hWT8ewJ6ENfLpgmprQql-UwYRLt6022yA9mmJ0340qoynnx0ZQe8Vrhw2A8ORCOBWy_Esh_nlPIfi4uLFALXoghKqRRPgWisy4bG9JLchV5kBGVgwubp6eUA4fPywgHUIrefTKW2xaTW9EraZbubTuLTWRI-JpDqJpuw_gWKkU6CbxeIObghlOqAQ5D0E-4MMjG_b5IoaVA3xsULyVR5wg0onfSMPouDQdkutxOF6Q9xU7OSQj8NX8rEiTxyK2QzKrs_y7G9-qunIv8Odtig5_O8qE618gPFb_Qt3Hj6Vt18OmcnIyrCcNeQaVDI2bt98FeubsmI8blOzViwqF3nYBVvujGA8uI5y5my3WjNeo_bx1LUSw1HUk5WkCtZ9Hv5F_z1yFhX7bu2Rs_8Der8ElQ?type=png)](https://mermaid.live/edit#pako:eNp9U9uO0zAQ_ZXBqEoRKW0Duw9-WAkWxAoJdkUqHlBepvaktXDsYDulZdV_x056WVi0fvBlzpmLfcb3TFhJjLPR6L4yAMqowKHfAmRhTQ1lHLIlesryh9Zv6BQuNfnsRI9Q61SDbndttXXJ7_n8sihe10fXM2NB23Bm1f14zHpnnST3RDStDJ3hWT8ewJ6ENfLpgmprQql-UwYRLt6022yA9mmJ0340qoynnx0ZQe8Vrhw2A8ORCOBWy_Esh_nlPIfi4uLFALXoghKqRRPgWisy4bG9JLchV5kBGVgwubp6eUA4fPywgHUIrefTKW2xaTW9EraZbubTuLTWRI-JpDqJpuw_gWKkU6CbxeIObghlOqAQ5D0E-4MMjG_b5IoaVA3xsULyVR5wg0onfSMPouDQdkutxOF6Q9xU7OSQj8NX8rEiTxyK2QzKrs_y7G9-qunIv8Odtig5_O8qE618gPFb_Qt3Hj6Vt18OmcnIyrCcNeQaVDI2bt98FeubsmI8blOzViwqF3nYBVvujGA8uI5y5my3WjNeo_bx1LUSw1HUk5WkCtZ9Hv5F_z1yFhX7bu2Rs_8Der8ElQ) The client discovers the Keycloak component definition and uses its `content-uuid` value to request it in YAML format [![](https://mermaid.ink/img/pako:eNqNU0tv2zAM_iushsAbZs-xmxaFUOSwbFgvHYYl2GHwRZboRJ0taZJcxC3y3yfbeTQoUIwHPfh9fIikngnXAgklk8lzoQCkkp7CcASI_AYbjChEJXMYxS-1v5iVrKzRRUd6gIyVDbPdQtfa9nbvsus8v6wOpifGCrf-xKoGec36rK1A-4a3Wio8wdNBXsAOuVbi7YQqrfxSPmEEAc5nZhuN0K7fwrKbTArl8G-LiuMXydaWNSPDIvdg1-X7aQzZdRZDfnX1YYQMs15yaZjysKglKv9av0T7iLZQIzKyIJnPP-4RCt--rmDjvXE0TXHLGlPjJ66b9DFLw2a0ChaJwKpvmtQqzfeSXAZJZqEWyU2_TE-SnUcL4Y7R7larH3CHTPQXxjk6B17_QfWfJotQyD4h3xkMDoypJWdDXh1ranpbWkjn96yDEs_QbVODtmeqB6cVjGHHUH1dkn0KFH6iC493IUo-ncGyHXK9gO_6kENg-NYqFKMPVILEpEHbMCnCrA_zWpBhjgtCw7Gf74KEZgcea71edooT6m2LMbG6XW8IrVjtwq01gvnDHBy1KKTX9n78SsOPiklo8m-tD5zdP_nfEJ0?type=png)](https://mermaid.live/edit#pako:eNqNU0tv2zAM_iushsAbZs-xmxaFUOSwbFgvHYYl2GHwRZboRJ0taZJcxC3y3yfbeTQoUIwHPfh9fIikngnXAgklk8lzoQCkkp7CcASI_AYbjChEJXMYxS-1v5iVrKzRRUd6gIyVDbPdQtfa9nbvsus8v6wOpifGCrf-xKoGec36rK1A-4a3Wio8wdNBXsAOuVbi7YQqrfxSPmEEAc5nZhuN0K7fwrKbTArl8G-LiuMXydaWNSPDIvdg1-X7aQzZdRZDfnX1YYQMs15yaZjysKglKv9av0T7iLZQIzKyIJnPP-4RCt--rmDjvXE0TXHLGlPjJ66b9DFLw2a0ChaJwKpvmtQqzfeSXAZJZqEWyU2_TE-SnUcL4Y7R7larH3CHTPQXxjk6B17_QfWfJotQyD4h3xkMDoypJWdDXh1ranpbWkjn96yDEs_QbVODtmeqB6cVjGHHUH1dkn0KFH6iC493IUo-ncGyHXK9gO_6kENg-NYqFKMPVILEpEHbMCnCrA_zWpBhjgtCw7Gf74KEZgcea71edooT6m2LMbG6XW8IrVjtwq01gvnDHBy1KKTX9n78SsOPiklo8m-tD5zdP_nfEJ0) 1. Client queries the OSCAL Content Registry for a list of available component definition files. a. Client -> Server: `GET https://example.com/v1/component-definition` b. Server -> Client: List of component definitions that includes `content-uuid`, `title`, `version`, `last-modified` and other metadata. (Always in JSON format.) 2. Client presents list of component definitions to the SSP author. 3. Author selects Keycloak component definition. 4. Client imports the component definition file for Keycloak in YAML format. a. Client -> Server: `GET https://example.com/v1/component-definition/` (HTTP Header: `Accept: application/xml`) 5. Server responds with b. Server -> Client: `oscal_keycloak_component.xml` (delivers the OSCAL Component Definition in XML format) Payload: Component Definition List ``` { "component-definition-list" : [ { "content-uuid": "22222222-3333-4000-8000-000000000001", "title": "First Component Definition", "last-modified": "2024-02-01T13:57:28.355446-04:00", "version": "20231012", "oscal-version": "1.1.2", "document-ids": [ { "identifier": "11111111-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/externaluuid" }, { "identifier": "22222222-3333-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/contentuuid" } ], "markings" : [], "remarks" : "" }, { "content-uuid": "22222222-3333-4000-8000-000000000002", "title": "Second Component Definition", "last-modified": "2024-02-01T13:57:28.355446-04:00", "version": "20231012", "oscal-version": "1.1.2", "document-ids": [ { "identifier": "11111111-3333-4000-8000-000000000002", "scheme": "http://oscal.io/oscal/identifier/externaluuid" }, { "identifier": "22222222-3333-4000-8000-000000000002", "scheme": "http://oscal.io/oscal/identifier/contentuuid" } ], "markings" : [], "remarks" : "" } ] } ``` Payload: OSCAL Component Definition in YAML Format ``` -component-definition: -metadata -component -back-matter ``` --- ## Scenario 2: Using Attachments **Client**: OSCAL-based SSP Authoring Tool **Server**: CISO's GRC Repository Managing attachments becomes critical when dealing with System Security Plans, Assessment Plans, Assessment Results, and Plans of Action of Milestones. Further, attachments can be quite large and often are not necessary when retrieving OSCAL content. The OSCAL REST OpenAPI Specification enables clients to handle each attachment individually as needed, while maintaining synchronicity with the core OSCAL artifact. This scenario walks through the lifecycle of delivering an SSP with attachments, later adding additional attachments, acquiring an SSP without attachments, later acquiring some of the attachments. ### Scenario 2A: Delivering an SSP With Attachments An SSP author delivers an OSCAL System Security Plan (SSP) to the ISSO's office for adjudication. The SSP is in OSCAL JSON format. It includes a boundary diagram attachment (`Boundary.pdf`) in the `resources`. with a UUID value of `11111111-2222-4000-8000-001000000001` Delivering an SSP and Attachments First, the client sends the OSCAL SSP to the server. [![](https://mermaid.ink/img/pako:eNqNU02P0zAQ_SuDUZUikn7B7sFCPVAOKyTYFS0cUC7TZNIaHNvYztKw6n_H-Wi7ZVcVPiT2e2_Gk8m8B5bpnBhng8FDqgCEEp5DuwWI_JZKijhEa3QUxY_Rb2gFriW56CgPlLGiRFsvtNS2iXs5vZ7N3hSH0JNiRTt_UhXteqp6r21O9kI2KRSd6Em7HtGOMq3yywUVWvml-EMRBHr21uyijto3r_DYDwapSpWjXxWpjD4I3FgsO42lzIPdrIeTGKbX0xhmV1evOsqg9SITBpWHhRSk_FN8SfaebJO9YToVJPP5657hcHe7XMHWe-P4eEw7LI2kUabL8f107GrnqUzCN1ZW-DoxEv_JFFKdMmEtNeYcyjp5LnL0w-kL4Ter1R3cEObNAbOMnAOvf9L_hixCl4Mi8bWhkMAYKTL0Qqtxc--7tZ0Pvzo6I3alBG3PoBoDJooGszrMCHoa9f3ubm26l_TVcPhCzujw5zjMJlNYWAr6_MW5vqn4oD_26LkGJVI4D0OUv7F28HF5-7m_mVTejVKqWMxKsiWKPDiqdUXKWrekjIdt46KUhZEKOqy8XtYqY9zbimJmdbXZMl6gdOFUmTzU2s_aEaVceG0_dYZtfRuzMEjftT5o9n8Bn044dg?type=png)](https://mermaid.live/edit#pako:eNqNU02P0zAQ_SuDUZUikn7B7sFCPVAOKyTYFS0cUC7TZNIaHNvYztKw6n_H-Wi7ZVcVPiT2e2_Gk8m8B5bpnBhng8FDqgCEEp5DuwWI_JZKijhEa3QUxY_Rb2gFriW56CgPlLGiRFsvtNS2iXs5vZ7N3hSH0JNiRTt_UhXteqp6r21O9kI2KRSd6Em7HtGOMq3yywUVWvml-EMRBHr21uyijto3r_DYDwapSpWjXxWpjD4I3FgsO42lzIPdrIeTGKbX0xhmV1evOsqg9SITBpWHhRSk_FN8SfaebJO9YToVJPP5657hcHe7XMHWe-P4eEw7LI2kUabL8f107GrnqUzCN1ZW-DoxEv_JFFKdMmEtNeYcyjp5LnL0w-kL4Ter1R3cEObNAbOMnAOvf9L_hixCl4Mi8bWhkMAYKTL0Qqtxc--7tZ0Pvzo6I3alBG3PoBoDJooGszrMCHoa9f3ubm26l_TVcPhCzujw5zjMJlNYWAr6_MW5vqn4oD_26LkGJVI4D0OUv7F28HF5-7m_mVTejVKqWMxKsiWKPDiqdUXKWrekjIdt46KUhZEKOqy8XtYqY9zbimJmdbXZMl6gdOFUmTzU2s_aEaVceG0_dYZtfRuzMEjftT5o9n8Bn044dg) Then, the client sends each SSP attachment to the server. [![](https://mermaid.ink/img/pako:eNp9k8Fu2zAMhl-F0xB4xew69tJi0KGHdYdeBhRLtsPgCyPRiTBb0iS5iFfk3SfbSZOiWHiQJf0fZVKknpkwkhhns9lzpQGUVoHDOAVIwpZaSjgka_SUpOe7P9EpXDfkkxc8StapFl1_bxrjBr_3xW1ZfqqPridiRbtwourR3lJfjJPkLpzWKE0neT7amexJGC0vB1QbHZbqLyUQ5XJhd8kk7YdPHPazWaUr7elPR1rQV4Ubh-3EOBIB3Gb9YZ5CcVukUN7cXE2SRReUUBZ1gPtGkQ5v95fknsgNpw_KREF2d_fxoHB4_LGCbQjW8zynHba2oWth2vypyH3vA7VZTLFzKvSZbVDnxcGyMlq2iLeRfR6G-ZnlGAKKbRt_doEvjnjxOroY3ik67BuDksPadOM1X1tZ_x9_WK0e4YFQDgsUgryHYH7TIf8JG_LPDu4cvpO3Jt49h3K-gGU3Or2beNISoNIsZS25FpWMXTx2YsXGDq0Yj9OhcysWyxg57IJZ9lowHlxHKXOm22wZr7HxcdVZieFY35ddkioY9216JONbSVks3i9jjsz-HwBw_Ps?type=png)](https://mermaid.live/edit#pako:eNp9k8Fu2zAMhl-F0xB4xew69tJi0KGHdYdeBhRLtsPgCyPRiTBb0iS5iFfk3SfbSZOiWHiQJf0fZVKknpkwkhhns9lzpQGUVoHDOAVIwpZaSjgka_SUpOe7P9EpXDfkkxc8StapFl1_bxrjBr_3xW1ZfqqPridiRbtwourR3lJfjJPkLpzWKE0neT7amexJGC0vB1QbHZbqLyUQ5XJhd8kk7YdPHPazWaUr7elPR1rQV4Ubh-3EOBIB3Gb9YZ5CcVukUN7cXE2SRReUUBZ1gPtGkQ5v95fknsgNpw_KREF2d_fxoHB4_LGCbQjW8zynHba2oWth2vypyH3vA7VZTLFzKvSZbVDnxcGyMlq2iLeRfR6G-ZnlGAKKbRt_doEvjnjxOroY3ik67BuDksPadOM1X1tZ_x9_WK0e4YFQDgsUgryHYH7TIf8JG_LPDu4cvpO3Jt49h3K-gGU3Or2beNISoNIsZS25FpWMXTx2YsXGDq0Yj9OhcysWyxg57IJZ9lowHlxHKXOm22wZr7HxcdVZieFY35ddkioY9216JONbSVks3i9jjsz-HwBw_Ps) 1. Client *optionally* inserts an *external identifier* into the metadata before sending it to the server. (For details, see [Scenario 1A](/docs/scenarios#scenario-1a-initial-delivery-of-a-component-definition) above.) 2. Client uses the REST POST method to send the System Security Plan to the OSCAL Content Registry. a. Client -> Server: `POST https://example.com/v1/system-security-plan` b. Payload: `my-system-security-plan.json` (may be XML, JSON, or YAML) c. HTTP Header: access token d. HTTP Header: `Content-type: application/json` (or `application/xml` or `application/yaml` as appropriate) 3. The CISO's GRC Repository receives and processes the file. a. The server verifies the access token has write access to the repository. b. The server verifies the content has valid syntax based on the content's declared OSCAL version (`oscal-version`). c. The server *optionally* stores a snapshot of the original content, exactly as it was received. d. The server checks for the existence of a content identifier and finds none. e. The server generates a v4 or v5 UUID and inserts it into the content's `//metadata/document-ids` array using `http://oscal.io/oscal/identifier/contentuuid` for the `scheme` value. (For details, see [Scenario 1A](/docs/scenarios#scenario-1a-initial-delivery-of-a-component-definition) above.) f. The server stores the modified version of the file as the working version. 4. The server responds to the client to indicate success and report the identifier to be used. a. Server -> Client: - Response: 201 Successfully created! - Payload: `system-security-plan-list` object in JSON with exactly one element in it. - For details, see [Scenario 1A](/docs/scenarios#scenario-1a-initial-delivery-of-a-component-definition) above. - For the uploaded SSP, the server returns a content UUID value of `11111111-2222-4000-8000-000000000000` 5. Client uploads each SSP attachment. a. Prior to upload, the SSP had the boundary diagram attached as a resource with a UUID value of `11111111-2222-4000-8000-001000000001` b. Using the content UUID received in step #4 and knowing the resource UUID of the boundary diagram from the SSP that was just uploaded, the client formulates a PUT request. - Client -> Server: `PUT https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000001` - Payload: `Boundary.pdf` - HTTP Header: Access Token c. The server verifies the access token has write permissions to the SSP. d. The server stores the attachment and revises the `rlink/href` value to `https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000001` e. Server returns status 204 Success 6. Client repeats step #2 as necessary for each additional attachment defined int the SSP's back-matter. Content Document Identifier (May be XML, JSON, or YAML) ``` { "system-security-plan-list" : [ { "content-uuid": "22222222-2222-4000-8000-000000000001", "title" : "System Security Plan for My System", "last-modified" : "2024-11-11T00:00:00Z", "oscal-version": "1.1.2", "document-ids": [ { "identifier": "11111111-2222-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/externaluuid" }, { "identifier": "22222222-2222-4000-8000-000000000001", "scheme": "http://oscal.io/oscal/identifier/contentuuid" } ], "markings" : [], "remarks" : "" } ] } ``` --- ### Scenario 2B: Adding a New Attachment to an SSP An SSP author wishes to add a new attachment to the SSP delivered above. The new attachment is a configuration management plan (`CM_plan.pdf`) that is not yet defined in the SSP's back-matter. The author wishes to include a title, version, date, and attachment type in the resource entry. Adding a New Attachment First, the client sends the new attachment. [![](https://mermaid.ink/img/pako:eNp9U21v0zAQ_iuHUZUhkqUJ24T8odIoHybEaEUqPqBIyLUvrSGxg-1sDVP_O07SpkUTuw9-uee5N9_5iXAtkFAymTzlCkAq6Sj0R4DAbbHCgEKwZhaD8Fz7jRnJ1iXaYKR7qDayYqad61Kbzu51cpOm74qj6Ymxwp07sYpenrM-aCPQvOCtlApP8LSXM9gi10q8nFChlcvkHwzAw-lVvQsGaN9tftlPJrnKlcXfDSqOHyXbGFYNHIPcgdmsL6YhJDdJCOn19ZsBqplxksuaKQfzUqJyz_UZmgc0nfcOGVgQzWZvDwiF5SJbwda52tI4xh2r6hIvua7ihyS2rXVYRb7GxkjXRnXJVJwcJEq9RFf-OaL33TI9k5g5x_i2GnM6RvahT5FZW2omKMzvfyy958taFP9n361WS7hDJroL4xytBad_4aG0gdaVFh3MKXxFW2v_rBTSaQJZ0xu9-pcfzUb6mM8im99-9i9vdWM4gl7_7JpwcVs-stb6-YVP2eILFNpUzB16gUoA5IqEpEKvlsLPez-zOelnOSfUH7sZz4lvuOexxumsVZxQZxoMidHNZktowUrrb00tmDtOwqhFIZ0298N36n9VSHybv2t95Oz_AnejD0w?type=png)](https://mermaid.live/edit#pako:eNp9U21v0zAQ_iuHUZUhkqUJ24T8odIoHybEaEUqPqBIyLUvrSGxg-1sDVP_O07SpkUTuw9-uee5N9_5iXAtkFAymTzlCkAq6Sj0R4DAbbHCgEKwZhaD8Fz7jRnJ1iXaYKR7qDayYqad61Kbzu51cpOm74qj6Ymxwp07sYpenrM-aCPQvOCtlApP8LSXM9gi10q8nFChlcvkHwzAw-lVvQsGaN9tftlPJrnKlcXfDSqOHyXbGFYNHIPcgdmsL6YhJDdJCOn19ZsBqplxksuaKQfzUqJyz_UZmgc0nfcOGVgQzWZvDwiF5SJbwda52tI4xh2r6hIvua7ihyS2rXVYRb7GxkjXRnXJVJwcJEq9RFf-OaL33TI9k5g5x_i2GnM6RvahT5FZW2omKMzvfyy958taFP9n361WS7hDJroL4xytBad_4aG0gdaVFh3MKXxFW2v_rBTSaQJZ0xu9-pcfzUb6mM8im99-9i9vdWM4gl7_7JpwcVs-stb6-YVP2eILFNpUzB16gUoA5IqEpEKvlsLPez-zOelnOSfUH7sZz4lvuOexxumsVZxQZxoMidHNZktowUrrb00tmDtOwqhFIZ0298N36n9VSHybv2t95Oz_AnejD0w) Then, the client sends any details for the OSCAL SSP's resource. [![](https://mermaid.ink/img/pako:eNp9k1Fv0zAQx7_KYVRlEwlpQjchP0wa5WFCsE2k4wHl5epcW4vEDrYzGqZ-d5ykWTtN9B4c2__fnS--8xMTuiDG2WTylCsAqaTj0E8BArehigIOwRItBeHx7g80Epcl2eAZ91JtZIWmnetSm87vbXKZph9Wo-uBWNDWHahVb6-pT9oUZE5EK6Wigzzt7Ui2JLQqTie00spl8i8F4OV0Vm-DQdp1Hz_sJpNc5crS74aUoM8S1wargTEkHJj18mwaQnKZhJBeXJwPUo3GSSFrVA7mpSTlXu9nZB7JdNE7ZaAgurp6t1c43D8sYONcbXkc0xaruqT3QlfxYxLb1jqqIv-LjZGujeoSVZzsLUq9RTN_G9HHbpgeWYzOodhU_rATfDLiaWzI6sYIepmmz_OQJralxoLDXTa__gqjA5xdl3-wtfAlu7uFlTYVuvP_R7lZLO7hhrDoFigEWQtO_6L9_QxYdz_R3p3Dd7K19rXhkE5nkDW905uBJ1UA5IqFrCJ_six8l_edmrO-g3PG_bTr7Jz5MnsOG6ezVgnGnWkoZEY36w3jKyytXzV1gW6s__MuFdJp8214RP1bCpkv7k-tR2b3D6iyB7U?type=png)](https://mermaid.live/edit#pako:eNp9k1Fv0zAQx7_KYVRlEwlpQjchP0wa5WFCsE2k4wHl5epcW4vEDrYzGqZ-d5ykWTtN9B4c2__fnS--8xMTuiDG2WTylCsAqaTj0E8BArehigIOwRItBeHx7g80Epcl2eAZ91JtZIWmnetSm87vbXKZph9Wo-uBWNDWHahVb6-pT9oUZE5EK6Wigzzt7Ui2JLQqTie00spl8i8F4OV0Vm-DQdp1Hz_sJpNc5crS74aUoM8S1wargTEkHJj18mwaQnKZhJBeXJwPUo3GSSFrVA7mpSTlXu9nZB7JdNE7ZaAgurp6t1c43D8sYONcbXkc0xaruqT3QlfxYxLb1jqqIv-LjZGujeoSVZzsLUq9RTN_G9HHbpgeWYzOodhU_rATfDLiaWzI6sYIepmmz_OQJralxoLDXTa__gqjA5xdl3-wtfAlu7uFlTYVuvP_R7lZLO7hhrDoFigEWQtO_6L9_QxYdz_R3p3Dd7K19rXhkE5nkDW905uBJ1UA5IqFrCJ_six8l_edmrO-g3PG_bTr7Jz5MnsOG6ezVgnGnWkoZEY36w3jKyytXzV1gW6s__MuFdJp8214RP1bCpkv7k-tR2b3D6iyB7U) 1. Client uses the content uuid from above to send the new SSP attachment. 1. Client -> Server: `POST https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment` - (Payload: `CM_plan.pdf`) 2. The CISO's GRC Repository receives and processes the file. a. The server verifies the access token has write access to the repository. b. Server generates a v4 or v5 UUID value for the attachment. (`11111111-2222-4000-8000-001000000002`) c. Server stores the attachment and associates the UUID with the attachment. d. Server creates a new back-matter resource in the SSP and assigns it the same UUID value. 3. The server returns the resource a. Server -> Client: The newly created resource entry (JSON), which includes the UUID value generated in step 2.b. above. (`11111111-2222-4000-8000-001000000002`) 4. The client is then able to send additional resource content, including the `title`, properties (`props`), and `remarks`. 1. Client -> Server: `PUT https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000002/resource` - Payload: updated resource content (Always in JSON format) --- ### Scenario 2C: Acquiring an SSP With Attachments An Assessment Lead needs to retrieve an OSCAL-based SSP from the ISSO office's GRC repository. The SSP includes a boundary diagram attachment (`Boundary.pdf`) in the OSCAL-SSP's `resources`: title 1. The assessor's tool retrieves a list of SSPs from the CISO's GRC Repository: 1. Client -> Server: `GET https://example.com/v1/system-security-plan` (HTTP Header: Access Token) 2. Server compiles list of SSPs to which the assessor has access based on access token. 3. Server -> Client: List of accessible SSPs, which includes `content-uuid`, `title`, `version`, `last-modified` and other metadata (JSON). 2. Client presents list of SSPs to the assessor. 3. Assessor selects the relevant SSP. 4. Client imports the SSP in YAML format. 1. Client -> Server: `GET https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000` (HTTP Headers: Access Token, `Accept: application/yaml`) 2. Server verifies the access token has read-permission for the SSP 3. Server -> Client: `oscal_system-security-plan.yaml` 5. Assessor reviews SSP and wishes to see the boundary diagram. 1. Client extracts first `rlink/href` value from the OSCAL SSP. 2. Client -> Server: `GET https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000001` - HTTP Header: Access Token 1. Server verifies the access token has read permission for the SSP 2. Server -> Client: `Boundary.pdf` 6. Assessor now wishes to see the CM Plan. 1. Client extracts first `rlink/href` value from the OSCAL SSP. 2. Client -> Server: `GET https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000002` (HTTP Header: Access Token) 3. Server verifies the access token has read permission for the SSP 4. Server -> Client: `Boundary.pdf` ![image.png](https://cdn.document360.io/fcf0031a-ef98-4389-b56d-d2beba546bdd/Images/Documentation/image%2812%29.png?sv=2026-02-06&spr=https&st=2026-11-08T02%3A24%3A45Z&se=2026-11-08T03%3A24%3A45Z&sr=c&sp=r&sig=DmDplMapNCa2jJMMqyARURoSYa3zHTULWhYevujgHg0%3D)