From c629f9cec8348b850aa9864c698d5448e4f54bd5 Mon Sep 17 00:00:00 2001 From: Jesse H Date: Tue, 25 Nov 2025 06:19:04 -0600 Subject: [PATCH 01/14] Add Architecture Report V1 API and schemas Introduces the ArchitectureReportV1 schema, supporting objects, and new API endpoints for submitting, retrieving, and deleting architecture reports and correlation records. Also adds the 'Architecture Reporting' tag to the API documentation. --- specs/Data-Gateway.json | 536 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 536 insertions(+) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index aa6ef54..b787ac7 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2227,6 +2227,303 @@ ] } ] + }, + "ArchitectureReportV1": { + "description": "Completely calculated architecture report structure that is the result of a complete run.", + "type": "object", + "properties": { + "correlation": { + "$ref": "#/components/schemas/CorrelationRecordV1" + }, + "principalData": { + "$ref": "#/components/schemas/PrincipalData" + }, + "tenantMetadata": { + "$ref": "#/components/schemas/ArchitectureReportV1.TenantMetadata" + } + }, + "required": [ + "correlation", + "tenantMetadata", + "principalData" + ], + "title": "Architecture Report V1 - Complete Object" + }, + "ArchitectureReportV1.CorrelationRecord": { + "$ref": "#/components/schemas/CorrelationRecordV1", + "description": "Metadata that describes the execution session (run) that is used to tie/relate architecture report versions together.", + "title": "Architecture Report V1 - CorrelationRecord" + }, + "ArchitectureReportV1.TenantMetadata": { + "description": "This is the the tenant data calculated for the architecture report", + "example": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "properties": { + "totalDeviceCount": { + "description": "The count of total devices within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "totalGuestCount": { + "description": "The count of total guests within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "totalMemberCount": { + "description": "The count of total members within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "totalUserCount": { + "description": "The count of total users within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + } + }, + "required": [ + "totalDeviceCount", + "totalGuestCount", + "totalMemberCount", + "totalUserCount" + ] + }, + "CorrelationRecordV0": { + "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", + "example": { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", + "reportTenantAccount": "ent-user@example.com", + "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", + "createdAt": "2024-08-01T21:13:12.821Z", + "updatedAt": "2024-08-01T21:13:12.821Z" + }, + "properties": { + "auditTenantAccount": { + "description": "The user account used to retrieve the report information in the tenant being audited.", + "examples": [ + "admin-user@example.com" + ], + "format": "email", + "type": "string" + }, + "correlationId": { + "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", + "examples": [ + "88da2253-758f-4135-9d37-64448c8b65c1" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "reportTenantAccount": { + "description": "User account used to store/report the report to the SHI Lab cloud service.", + "examples": [ + "generic-user@example.com" + ], + "format": "email", + "type": "string" + }, + "tenantId": { + "description": "Unique ID of customer's Microsoft tenant that the report is auditing.", + "examples": [ + "0e1fe83f-a33f-4250-8546-225b8d45ae01" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "createdAt": { + "description": "Timestamp of when the report was created.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of when the report was last updated.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "auditTenantAccount" + ], + "title": "Correlation Record V0", + "type": "object" + }, + "CorrelationRecordV1": { + "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", + "example": { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "b7e2c8a1-4f3a-4e2b-9c6d-2a1e8f7b3c2d", + "isMigrating": false, + "reportTenantAccount": "ent-user@example.com", + "schemaVersion": 1, + "tenantId": "f2a4d7c3-8b1e-4e5a-9c2d-7e3b6a1f4c8d", + "createdAt": "2025-01-01T00:00:00Z", + "updatedAt": "2025-01-02T00:00:00Z" + }, + "properties": { + "auditTenantAccount": { + "description": "The user account used to retrieve the report information in the tenant being audited.", + "examples": [ + "admin-user@example.com" + ], + "format": "email", + "type": "string" + }, + "correlationId": { + "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", + "examples": [ + "88da2253-758f-4135-9d37-64448c8b65c1" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "isMigrating": { + "description": "Flag to show when the stored report is migrating to a newer version.", + "examples": [ + true + ], + "type": "boolean" + }, + "reportTenantAccount": { + "description": "User account used to store/report the report to the SHI Lab cloud service.", + "examples": [ + "generic-user@example.com" + ], + "format": "email", + "type": "string" + }, + "schemaVersion": { + "description": "Version number of the rendered report", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "tenantId": { + "description": "Unique ID of customer's Microsoft tenant that the report is auditing.", + "examples": [ + "0e1fe83f-a33f-4250-8546-225b8d45ae01" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "createdAt": { + "description": "Timestamp of when the report was created.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of when the report was last updated.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "auditTenantAccount" + ], + "title": "Correlation Record V1", + "type": "object" + }, + "ArchitectureReport.PrincipalData": { + "$ref": "#/components/schemas/PrincipalData" + }, + "PrincipalData": { + "description": "placeholder", + "example": { + "device": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": { + "FeatureA": true, + "FeatureB": false + }, + "d76878d6-1495-4243-a334-a82bb9818cd0": 10 + }, + "assignedLicense": { + "id": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", + "servicePlanList": [ + "547404d4-8734-415f-a7ca-e9c1ffb95e48" + ] + }, + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": { + "FeatureA": true, + "FeatureB": true + }, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": null + }, + "principalMetadata": { + "sharedComputer": true + } + } + }, + "user": { + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": { + "FeatureA": false, + "FeatureB": true + } + }, + "assignedLicense": { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "f8ec916b-97b5-4687-b960-9afb8ed5e85e" + ] + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": 5, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "FeatureA": true, + "FeatureB": false + } + }, + "enhancedData": null, + "llmInferred": { + "isServiceAccount": true, + "isFrontlineWorker": false, + "isTempWorker": false + }, + "principalMetadata": { + "sharedMailbox": false + } + } + } + }, + "type": "object" } }, "securitySchemes": { @@ -5996,6 +6293,241 @@ "Tenant Records" ] } + }, + "/Api/V1/ArchitectureReport": { + "post": { + "summary": "Submit Architecture Report V1", + "description": "Submits an Architecture Report V1 payload to the Architecture Report endpoint.", + "operationId": "/Api/V1/ArchitectureReport", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "responses": { + "201": { + "description": "Architecture Report V1 submitted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "tags": [ + "Architecture Reporting" + ] + } + }, + "/Api/V1/ArchitectureReport/Correlation": { + "get": { + "summary": "Get Correlation Records", + "description": "Retrieves a list of correlation records, optionally filtered by date range.", + "operationId": "/Api/V1/ArchitectureReport/Correlation", + "parameters": [ + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "description": "A list of correlation records.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CorrelationRecordV1" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Architecture Reporting" + ] + } + }, + "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}": { + "get": { + "summary": "Get Correlation Records by Tenant", + "description": "Retrieves a list of correlation records for a specific tenant.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "200": { + "description": "A list of correlation records for the specified tenant.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CorrelationRecordV1" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Architecture Reporting" + ] + } + }, + "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data": { + "delete": { + "summary": "Delete Architecture Report Data by Correlation ID", + "description": "Deletes the architecture report data associated with the specified correlation ID.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "204": { + "description": "Architecture report data deleted successfully." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Architecture Reporting" + ] + }, + "get": { + "summary": "Get Architecture Report Data by Correlation ID", + "description": "Retrieves the architecture report data associated with the specified correlation ID.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "200": { + "description": "The architecture report data for the specified correlation ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "400": { + "description": "Bad Request. The correlation ID is invalid." + }, + "404": { + "description": "Not Found. No data found for the specified correlation ID." + } + }, + "tags": [ + "Architecture Reporting" + ] + } + }, + "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { + "delete": { + "summary": "Delete Architecture Report Data by Correlation ID and Tenant ID", + "description": "Deletes the architecture report data associated with the specified correlation ID and tenant ID.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId", + "required": true + }, + { + "$ref": "#/components/parameters/tenantId", + "required": true + } + ], + "responses": { + "204": { + "description": "Architecture report data deleted successfully." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Architecture Reporting" + ] + }, + "get": { + "summary": "Get Architecture Report Data by Correlation ID and Tenant ID", + "description": "Retrieves the architecture report data associated with the specified correlation ID and tenant ID.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId", + "required": true + }, + { + "$ref": "#/components/parameters/tenantId", + "required": true + } + ], + "responses": { + "200": { + "description": "The architecture report data for the specified correlation ID and tenant ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Architecture Reporting" + ] + } } }, "security": [ @@ -6034,6 +6566,10 @@ "description": "Manages and reports the list of purchased licenses for the various SHI Lab Products.", "name": "License Entitlement" }, + { + "description": "Collects and reports data about a tenant's architecture.", + "name": "Architecture Reporting" + }, { "description": "Collects data from the various SHI Lab products.", "name": "Telemetry" From 07237344f7fe3d9dd3c12c82498220bfeb0850e9 Mon Sep 17 00:00:00 2001 From: Jesse H Date: Wed, 26 Nov 2025 05:09:09 -0600 Subject: [PATCH 02/14] Refactor example fields to examples arrays in schema Replaces 'example' fields with 'examples' arrays for multiple schema objects to improve consistency and support OpenAPI standards. Also adds new CommonPrincipalAssignment, DevicePrincipalAssignment, and UserPrincipalAssignment schema definitions. --- specs/Data-Gateway.json | 193 +++++++++++++++++++++++----------------- 1 file changed, 113 insertions(+), 80 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index b787ac7..1597e98 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2256,12 +2256,14 @@ }, "ArchitectureReportV1.TenantMetadata": { "description": "This is the the tenant data calculated for the architecture report", - "example": { - "totalDeviceCount": 1, - "totalGuestCount": 1, - "totalMemberCount": 1, - "totalUserCount": 1 - }, + "examples": [ + { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + } + ], "properties": { "totalDeviceCount": { "description": "The count of total devices within the tenant", @@ -2305,14 +2307,16 @@ }, "CorrelationRecordV0": { "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", - "example": { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", - "reportTenantAccount": "ent-user@example.com", - "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", - "createdAt": "2024-08-01T21:13:12.821Z", - "updatedAt": "2024-08-01T21:13:12.821Z" - }, + "examples": [ + { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", + "reportTenantAccount": "ent-user@example.com", + "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", + "createdAt": "2024-08-01T21:13:12.821Z", + "updatedAt": "2024-08-01T21:13:12.821Z" + } + ], "properties": { "auditTenantAccount": { "description": "The user account used to retrieve the report information in the tenant being audited.", @@ -2373,16 +2377,18 @@ }, "CorrelationRecordV1": { "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", - "example": { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "b7e2c8a1-4f3a-4e2b-9c6d-2a1e8f7b3c2d", - "isMigrating": false, - "reportTenantAccount": "ent-user@example.com", - "schemaVersion": 1, - "tenantId": "f2a4d7c3-8b1e-4e5a-9c2d-7e3b6a1f4c8d", - "createdAt": "2025-01-01T00:00:00Z", - "updatedAt": "2025-01-02T00:00:00Z" - }, + "examples": [ + { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "b7e2c8a1-4f3a-4e2b-9c6d-2a1e8f7b3c2d", + "isMigrating": false, + "reportTenantAccount": "ent-user@example.com", + "schemaVersion": 1, + "tenantId": "f2a4d7c3-8b1e-4e5a-9c2d-7e3b6a1f4c8d", + "createdAt": "2025-01-01T00:00:00Z", + "updatedAt": "2025-01-02T00:00:00Z" + } + ], "properties": { "auditTenantAccount": { "description": "The user account used to retrieve the report information in the tenant being audited.", @@ -2461,70 +2467,97 @@ }, "PrincipalData": { "description": "placeholder", - "example": { - "device": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": { - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": { - "FeatureA": true, - "FeatureB": false + "examples": [ + { + "device": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": { + "FeatureA": true, + "FeatureB": false + }, + "d76878d6-1495-4243-a334-a82bb9818cd0": 10 }, - "d76878d6-1495-4243-a334-a82bb9818cd0": 10 - }, - "assignedLicense": { - "id": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", - "servicePlanList": [ - "547404d4-8734-415f-a7ca-e9c1ffb95e48" - ] - }, - "consumedService": { - "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": { - "FeatureA": true, - "FeatureB": true + "assignedLicense": { + "id": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", + "servicePlanList": [ + "547404d4-8734-415f-a7ca-e9c1ffb95e48" + ] }, - "c63b7a2d-6573-4c37-9ca8-e12b954d3198": null - }, - "principalMetadata": { - "sharedComputer": true - } - } - }, - "user": { - "04e88835-771a-482b-9d6f-ba06c32cbb67": { - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": { - "FeatureA": false, - "FeatureB": true + "consumedService": { + "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": { + "FeatureA": true, + "FeatureB": true + }, + "c63b7a2d-6573-4c37-9ca8-e12b954d3198": null + }, + "principalMetadata": { + "sharedComputer": true } - }, - "assignedLicense": { - "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", - "servicePlanList": [ - "f8ec916b-97b5-4687-b960-9afb8ed5e85e" - ] - }, - "consumedService": { - "9d3603de-b378-4c4a-adcc-ee133cbef914": 5, - "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { - "FeatureA": true, - "FeatureB": false + } + }, + "user": { + "04e88835-771a-482b-9d6f-ba06c32cbb67": { + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": { + "FeatureA": false, + "FeatureB": true + } + }, + "assignedLicense": { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "f8ec916b-97b5-4687-b960-9afb8ed5e85e" + ] + }, + "consumedService": { + "9d3603de-b378-4c4a-adcc-ee133cbef914": 5, + "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { + "FeatureA": true, + "FeatureB": false + } + }, + "enhancedData": null, + "llmInferred": { + "isServiceAccount": true, + "isFrontlineWorker": false, + "isTempWorker": false + }, + "principalMetadata": { + "sharedMailbox": false } - }, - "enhancedData": null, - "llmInferred": { - "isServiceAccount": true, - "isFrontlineWorker": false, - "isTempWorker": false - }, - "principalMetadata": { - "sharedMailbox": false } } } - }, + ], "type": "object" - } + }, + "CommonPrincipalAssignment": { + "properties": { + "assignedService": { + "oneOf": [ + { + "$ref": "#/components/schemas/FeatureBreakdown" + }, + { + "type": "integer", + "format": "int32", + "examples": [ + 0 + ] + }, + { + "type": "null" + } + ] + }, + "assignedLicense": [], + "consumedService": {} + } + }, + "DevicePrincipalAssignment": {}, + "UserPrincipalAssignment": {} }, "securitySchemes": { "EntraID": { From 2de7464fc676704cbe85e8b7a94a5ae3901870ea Mon Sep 17 00:00:00 2001 From: Jesse H Date: Wed, 26 Nov 2025 12:14:14 -0600 Subject: [PATCH 03/14] Refactor schema references and principal data descriptions ***WIP*** Replaces inline definitions of LicenseReport.CorrelationRecord and CorrelationRecordV0 with references to Report.CorrelationRecordV0. Updates references and descriptions for principal data and correlation records in architecture and report schemas for consistency. Also renames CommonPrincipalAssignment to Report.CommonPrincipalAssignment and updates related references. --- specs/Data-Gateway.json | 385 +++++++++------------------------------- 1 file changed, 86 insertions(+), 299 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 1597e98..2108761 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -439,73 +439,8 @@ }, "LicenseReport.CorrelationRecord": { "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", - "examples": [ - { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", - "reportTenantAccount": "ent-user@example.com", - "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", - "createdAt": "2024-08-01T21:13:12.821Z", - "updatedAt": "2024-08-01T21:13:12.821Z" - } - ], - "properties": { - "auditTenantAccount": { - "description": "The user account used to retrieve the license information in the tenant being audited.", - "examples": [ - "admin-user@example.com" - ], - "format": "email", - "type": "string" - }, - "correlationId": { - "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", - "examples": [ - "88da2253-758f-4135-9d37-64448c8b65c1" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "reportTenantAccount": { - "description": "User account used to store/report the license report to the SHI Lab cloud service.", - "examples": [ - "generic-user@example.com" - ], - "format": "email", - "type": "string" - }, - "tenantId": { - "description": "Unique ID of customer's Microsoft tenant that the license report is for.", - "examples": [ - "0e1fe83f-a33f-4250-8546-225b8d45ae01" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "createdAt": { - "description": "Timestamp of when the report was created.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - }, - "updatedAt": { - "description": "Timestamp of when the report was last updated.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - } - }, - "required": [ - "auditTenantAccount" - ], - "title": "License Report - Correlation Record", - "type": "object" + "$ref": "#/components/schemas/Report.CorrelationRecordV0", + "title": "License Report - Correlation Record" }, "LicenseReport.LicenseData": { "type": "object", @@ -923,6 +858,81 @@ ], "title": "License Report V1 - Complete Object" }, + "Report.CorrelationRecordV0": { + "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", + "examples": [ + { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", + "reportTenantAccount": "ent-user@example.com", + "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", + "createdAt": "2024-08-01T21:13:12.821Z", + "updatedAt": "2024-08-01T21:13:12.821Z" + } + ], + "properties": { + "auditTenantAccount": { + "description": "The user account used to retrieve the report information in the tenant being audited.", + "examples": [ + "admin-user@example.com" + ], + "format": "email", + "type": "string" + }, + "correlationId": { + "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", + "examples": [ + "88da2253-758f-4135-9d37-64448c8b65c1" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "reportTenantAccount": { + "description": "User account used to store/report the report to the SHI Lab cloud service.", + "examples": [ + "generic-user@example.com" + ], + "format": "email", + "type": "string" + }, + "tenantId": { + "description": "Unique ID of customer's Microsoft tenant that the report is auditing.", + "examples": [ + "0e1fe83f-a33f-4250-8546-225b8d45ae01" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "createdAt": { + "description": "Timestamp of when the report was created.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of when the report was last updated.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "auditTenantAccount", + "correlationId", + "reportTenantAccount", + "tenantId", + "createdAt", + "updatedAt" + ], + "title": "Report - Correlation Record V0", + "type": "object" + }, "Report.CorrelationRecordV1": { "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", "examples": [ @@ -1016,7 +1026,7 @@ "type": "object" }, "Report.PrincipalData": { - "description": "Contains user and device records included in the license report, detailing assigned services, licenses, consumed services, and related metadata for each principal. ", + "description": "Contains user and device records included in the report, detailing assigned services, licenses, consumed services, and related metadata for each principal.", "type": "object", "required": [ "device", @@ -2233,10 +2243,10 @@ "type": "object", "properties": { "correlation": { - "$ref": "#/components/schemas/CorrelationRecordV1" + "$ref": "#/components/schemas/ArchitectureReportV1.CorrelationRecord" }, "principalData": { - "$ref": "#/components/schemas/PrincipalData" + "$ref": "#/components/schemas/ArchitectureReport.PrincipalData" }, "tenantMetadata": { "$ref": "#/components/schemas/ArchitectureReportV1.TenantMetadata" @@ -2250,7 +2260,7 @@ "title": "Architecture Report V1 - Complete Object" }, "ArchitectureReportV1.CorrelationRecord": { - "$ref": "#/components/schemas/CorrelationRecordV1", + "$ref": "#/components/schemas/Report.CorrelationRecordV1", "description": "Metadata that describes the execution session (run) that is used to tie/relate architecture report versions together.", "title": "Architecture Report V1 - CorrelationRecord" }, @@ -2305,240 +2315,17 @@ "totalUserCount" ] }, - "CorrelationRecordV0": { - "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", - "examples": [ - { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", - "reportTenantAccount": "ent-user@example.com", - "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", - "createdAt": "2024-08-01T21:13:12.821Z", - "updatedAt": "2024-08-01T21:13:12.821Z" - } - ], - "properties": { - "auditTenantAccount": { - "description": "The user account used to retrieve the report information in the tenant being audited.", - "examples": [ - "admin-user@example.com" - ], - "format": "email", - "type": "string" - }, - "correlationId": { - "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", - "examples": [ - "88da2253-758f-4135-9d37-64448c8b65c1" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "reportTenantAccount": { - "description": "User account used to store/report the report to the SHI Lab cloud service.", - "examples": [ - "generic-user@example.com" - ], - "format": "email", - "type": "string" - }, - "tenantId": { - "description": "Unique ID of customer's Microsoft tenant that the report is auditing.", - "examples": [ - "0e1fe83f-a33f-4250-8546-225b8d45ae01" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "createdAt": { - "description": "Timestamp of when the report was created.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - }, - "updatedAt": { - "description": "Timestamp of when the report was last updated.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - } - }, - "required": [ - "auditTenantAccount" - ], - "title": "Correlation Record V0", - "type": "object" - }, - "CorrelationRecordV1": { - "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", - "examples": [ - { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "b7e2c8a1-4f3a-4e2b-9c6d-2a1e8f7b3c2d", - "isMigrating": false, - "reportTenantAccount": "ent-user@example.com", - "schemaVersion": 1, - "tenantId": "f2a4d7c3-8b1e-4e5a-9c2d-7e3b6a1f4c8d", - "createdAt": "2025-01-01T00:00:00Z", - "updatedAt": "2025-01-02T00:00:00Z" - } - ], - "properties": { - "auditTenantAccount": { - "description": "The user account used to retrieve the report information in the tenant being audited.", - "examples": [ - "admin-user@example.com" - ], - "format": "email", - "type": "string" - }, - "correlationId": { - "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", - "examples": [ - "88da2253-758f-4135-9d37-64448c8b65c1" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "isMigrating": { - "description": "Flag to show when the stored report is migrating to a newer version.", - "examples": [ - true - ], - "type": "boolean" - }, - "reportTenantAccount": { - "description": "User account used to store/report the report to the SHI Lab cloud service.", - "examples": [ - "generic-user@example.com" - ], - "format": "email", - "type": "string" - }, - "schemaVersion": { - "description": "Version number of the rendered report", - "examples": [ - 1 - ], - "format": "int32", - "type": "integer" - }, - "tenantId": { - "description": "Unique ID of customer's Microsoft tenant that the report is auditing.", - "examples": [ - "0e1fe83f-a33f-4250-8546-225b8d45ae01" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "createdAt": { - "description": "Timestamp of when the report was created.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - }, - "updatedAt": { - "description": "Timestamp of when the report was last updated.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - } - }, - "required": [ - "auditTenantAccount" - ], - "title": "Correlation Record V1", - "type": "object" - }, "ArchitectureReport.PrincipalData": { - "$ref": "#/components/schemas/PrincipalData" - }, - "PrincipalData": { - "description": "placeholder", - "examples": [ - { - "device": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": { - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": { - "FeatureA": true, - "FeatureB": false - }, - "d76878d6-1495-4243-a334-a82bb9818cd0": 10 - }, - "assignedLicense": { - "id": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", - "servicePlanList": [ - "547404d4-8734-415f-a7ca-e9c1ffb95e48" - ] - }, - "consumedService": { - "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": { - "FeatureA": true, - "FeatureB": true - }, - "c63b7a2d-6573-4c37-9ca8-e12b954d3198": null - }, - "principalMetadata": { - "sharedComputer": true - } - } - }, - "user": { - "04e88835-771a-482b-9d6f-ba06c32cbb67": { - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": { - "FeatureA": false, - "FeatureB": true - } - }, - "assignedLicense": { - "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", - "servicePlanList": [ - "f8ec916b-97b5-4687-b960-9afb8ed5e85e" - ] - }, - "consumedService": { - "9d3603de-b378-4c4a-adcc-ee133cbef914": 5, - "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { - "FeatureA": true, - "FeatureB": false - } - }, - "enhancedData": null, - "llmInferred": { - "isServiceAccount": true, - "isFrontlineWorker": false, - "isTempWorker": false - }, - "principalMetadata": { - "sharedMailbox": false - } - } - } - } - ], - "type": "object" + "description": "Contains user and device records included in the architecture report, detailing assigned services, licenses, consumed services, and related metadata for each principal.", + "$ref": "#/components/schemas/Report.PrincipalData", + "title": "Architecture Report - Principal Data" }, - "CommonPrincipalAssignment": { + "Report.CommonPrincipalAssignment": { "properties": { "assignedService": { "oneOf": [ { - "$ref": "#/components/schemas/FeatureBreakdown" + "$ref": "#/components/schemas/Report.FeatureBreakdown" }, { "type": "integer", From 36bb8934f4f775e1cf690f47fc34d8985b571640 Mon Sep 17 00:00:00 2001 From: Jesse H Date: Mon, 1 Dec 2025 06:04:47 -0600 Subject: [PATCH 04/14] Update Architecture Report API endpoints and responses Refined operationId naming for clarity and consistency across endpoints. Enhanced endpoint descriptions with permission and access details. Added 401 and 403 error responses to relevant endpoints. Updated schema references and parameter lists for improved accuracy. --- specs/Data-Gateway.json | 85 +++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 20 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 2108761..482cae6 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -6118,7 +6118,7 @@ "post": { "summary": "Submit Architecture Report V1", "description": "Submits an Architecture Report V1 payload to the Architecture Report endpoint.", - "operationId": "/Api/V1/ArchitectureReport", + "operationId": "/Api/V1/ArchitectureReport/Post", "parameters": [], "requestBody": { "required": true, @@ -6143,6 +6143,12 @@ }, "400": { "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" } }, "tags": [ @@ -6153,8 +6159,8 @@ "/Api/V1/ArchitectureReport/Correlation": { "get": { "summary": "Get Correlation Records", - "description": "Retrieves a list of correlation records, optionally filtered by date range.", - "operationId": "/Api/V1/ArchitectureReport/Correlation", + "description": "Retrieves the list of correlation records for the authenticated tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/Get", "parameters": [ { "$ref": "#/components/parameters/dateStart" @@ -6171,7 +6177,7 @@ "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/CorrelationRecordV1" + "$ref": "#/components/schemas/Report.CorrelationRecordV1" } } } @@ -6180,6 +6186,12 @@ "400": { "$ref": "#/components/responses/400" }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" } @@ -6192,11 +6204,17 @@ "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}": { "get": { "summary": "Get Correlation Records by Tenant", - "description": "Retrieves a list of correlation records for a specific tenant.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}", + "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, or `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" } ], "responses": { @@ -6216,6 +6234,12 @@ "400": { "$ref": "#/components/responses/400" }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" } @@ -6228,8 +6252,8 @@ "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data": { "delete": { "summary": "Delete Architecture Report Data by Correlation ID", - "description": "Deletes the architecture report data associated with the specified correlation ID.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data", + "description": "Deletes the full license report v1 for the specified correlation ID.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data/Delete", "parameters": [ { "$ref": "#/components/parameters/correlationId" @@ -6242,8 +6266,11 @@ "400": { "$ref": "#/components/responses/400" }, - "404": { - "$ref": "#/components/responses/404" + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" } }, "tags": [ @@ -6251,9 +6278,9 @@ ] }, "get": { - "summary": "Get Architecture Report Data by Correlation ID", - "description": "Retrieves the architecture report data associated with the specified correlation ID.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data", + "summary": "Retrieve the specified Architecture Report V1 by Correlation ID", + "description": "Retrieves the full license report v1 for the specified correlation ID in the authenticated tenant. The license report v1 contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data/Get", "parameters": [ { "$ref": "#/components/parameters/correlationId" @@ -6271,10 +6298,16 @@ } }, "400": { - "description": "Bad Request. The correlation ID is invalid." + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" }, "404": { - "description": "Not Found. No data found for the specified correlation ID." + "$ref": "#/components/responses/404" } }, "tags": [ @@ -6284,9 +6317,9 @@ }, "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { "delete": { - "summary": "Delete Architecture Report Data by Correlation ID and Tenant ID", - "description": "Deletes the architecture report data associated with the specified correlation ID and tenant ID.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data", + "summary": "Delete the specified Architecture Report V1 for specified tenant", + "description": "Deletes the full architecture report v1 for the specified correlation ID and tenant.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data/Delete", "parameters": [ { "$ref": "#/components/parameters/correlationId", @@ -6304,6 +6337,12 @@ "400": { "$ref": "#/components/responses/400" }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" } @@ -6313,9 +6352,9 @@ ] }, "get": { - "summary": "Get Architecture Report Data by Correlation ID and Tenant ID", + "summary": "Get Architecture Report v1 Data by Correlation ID and Tenant ID", "description": "Retrieves the architecture report data associated with the specified correlation ID and tenant ID.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data", + "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data/Get", "parameters": [ { "$ref": "#/components/parameters/correlationId", @@ -6340,6 +6379,12 @@ "400": { "$ref": "#/components/responses/400" }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" } From 2f59617a396f1bb1be4358519cc2a2743429a4dd Mon Sep 17 00:00:00 2001 From: Jesse H Date: Mon, 1 Dec 2025 14:08:51 -0600 Subject: [PATCH 05/14] Update API error responses to use 500 status code Replaces various 401, 403, and 404 error responses with a unified 500 Internal Server Error response across multiple endpoints in Data-Gateway.json. Adds a description for the 500 error and changes some success response codes from 201 to 200 for consistency. --- specs/Data-Gateway.json | 74 +++++++++-------------------------------- 1 file changed, 16 insertions(+), 58 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 482cae6..7380b5e 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -3094,7 +3094,7 @@ } }, "responses": { - "201": { + "200": { "content": { "application/json": { "examples": { @@ -3563,9 +3563,6 @@ "201": { "description": "Deleted successfully" }, - "204": { - "description": "Deleted successfully" - }, "400": { "$ref": "#/components/responses/400" }, @@ -3735,9 +3732,6 @@ "201": { "description": "Deleted successfully" }, - "204": { - "description": "Deleted successfully" - }, "400": { "$ref": "#/components/responses/400" }, @@ -6131,7 +6125,7 @@ } }, "responses": { - "201": { + "200": { "description": "Architecture Report V1 submitted successfully.", "content": { "application/json": { @@ -6144,11 +6138,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ @@ -6186,14 +6177,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ @@ -6234,14 +6219,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ @@ -6266,11 +6245,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ @@ -6300,14 +6276,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ @@ -6337,14 +6307,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ @@ -6379,14 +6343,8 @@ "400": { "$ref": "#/components/responses/400" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" + "500": { + "$ref": "#/components/responses/500" } }, "tags": [ From 9686cfbb76c07d54c43e55f66118b07d5cca0fb1 Mon Sep 17 00:00:00 2001 From: JagdishKhunti Date: Tue, 2 Dec 2025 13:22:14 +0000 Subject: [PATCH 06/14] LAB-980 Updated the Data-Gateway JSON schema to clarify and expand user and device principal records, including required fields and more detailed property definitions. Enhanced the structure and examples for inferred attributes and enhanced identity data, added explicit nullability, and improved descriptions for service plan and license references. These changes improve schema accuracy and documentation for integrators. --- specs/Data-Gateway.json | 89 ++++++++++++++++++++++++++++++++--------- 1 file changed, 71 insertions(+), 18 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 7380b5e..dc83c7f 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -1036,6 +1036,14 @@ "user": { "title": "User Principal Records", "type": "object", + "required": [ + "assignedService", + "assignedLicense", + "consumedService", + "llmInferred", + "principalMetadata", + "enhancedData" + ], "description": "Object containing user records, each keyed by user ID. Includes assigned services, licenses, consumed services, inferred attributes, metadata, and enhanced identity data for each user.", "additionalProperties": { "type": "object", @@ -1068,36 +1076,75 @@ "description": "Inferred principal attributes, showing if the account is a service account, frontline worker, temporary worker.", "properties": { "isServiceAccount": { - "description": "Indicates if the account is a service account.", - "type": [ - "boolean", - "null" + "description": "The user service account; may be null if not provided.", + "oneOf": [ + { + "type": "boolean", + "description": "Indicates if the account is a service account.", + "examples": [ + true + ] + }, + { + "type": "null", + "description": "No data or unused." + } ], "examples": [ - true, - null + { + "isServiceAccount": true + }, + { + "isServiceAccount": null + } ] }, "isFrontlineWorker": { - "description": "Indicates if the user is a frontline worker.", - "type": [ - "boolean", - "null" + "description": "The user a temporary employee; may be null if not provided.", + "oneOf": [ + { + "type": "boolean", + "description": "Indicates if the user is a frontline worker.", + "examples": [ + true + ] + }, + { + "type": "null", + "description": "No data or unused." + } ], "examples": [ - true, - null + { + "isFrontlineWorker": true + }, + { + "isFrontlineWorker": null + } ] }, "isTempWorker": { - "description": "Indicates if the user is a temporary worker.", - "type": [ - "boolean", - "null" + "description": "The user is a temporary worker; may be bull if not provided.", + "oneOf": [ + { + "type": "boolean", + "description": "Indicates if the user is a temporary worker.", + "examples": [ + true + ] + }, + { + "type": "null", + "description": "No data or unused." + } ], "examples": [ - true, - null + { + "isTempWorker": true + }, + { + "isTempWorker": null + } ] } }, @@ -1251,6 +1298,12 @@ "device": { "title": "Device Principal Records", "type": "object", + "required": [ + "assignedService", + "assignedLicense", + "consumedService", + "principalMetadata" + ], "description": "Object containing device records, each keyed by device ID. Includes assigned services, licenses, consumed services, and metadata for each device.", "additionalProperties": { "type": "object", From 5e2f5fcf94ac79b1774de0ae8412888285c0eb54 Mon Sep 17 00:00:00 2001 From: Jesse H Date: Tue, 2 Dec 2025 07:47:39 -0600 Subject: [PATCH 07/14] Add permission details to ArchitectureReport endpoints Updated the descriptions for the POST and GET /Api/V1/ArchitectureReport endpoints to specify required scopes and tenant access restrictions for improved API documentation clarity. --- specs/Data-Gateway.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index dc83c7f..be789b2 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -6164,7 +6164,7 @@ "/Api/V1/ArchitectureReport": { "post": { "summary": "Submit Architecture Report V1", - "description": "Submits an Architecture Report V1 payload to the Architecture Report endpoint.", + "description": "Submits an Architecture Report V1 payload to the Architecture Report endpoint.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, `ArchitectureReport.ReadWrite.All` scope (permission).", "operationId": "/Api/V1/ArchitectureReport/Post", "parameters": [], "requestBody": { @@ -6370,7 +6370,7 @@ }, "get": { "summary": "Get Architecture Report v1 Data by Correlation ID and Tenant ID", - "description": "Retrieves the architecture report data associated with the specified correlation ID and tenant ID.", + "description": "Retrieves the architecture report data associated with the specified correlation ID and tenant ID.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data/Get", "parameters": [ { From 16d9755db997b9bce9726ab7c8630b85cfac002d Mon Sep 17 00:00:00 2001 From: Jesse H Date: Tue, 2 Dec 2025 18:41:04 -0600 Subject: [PATCH 08/14] Revise Data-Gateway schema for user and device records Updated required fields and descriptions for user and device principal records, improved enhanced identity data structure to support consent-based nullability, and clarified examples and titles for correlation and principal metadata records. These changes improve schema clarity, flexibility, and alignment with consent requirements. --- specs/Data-Gateway.json | 100 +++++++++------------------------------- 1 file changed, 21 insertions(+), 79 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index be789b2..2f65d5e 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -872,7 +872,7 @@ ], "properties": { "auditTenantAccount": { - "description": "The user account used to retrieve the report information in the tenant being audited.", + "description": "The user account used to retrieve the information in the tenant being audited.", "examples": [ "admin-user@example.com" ], @@ -923,14 +923,9 @@ } }, "required": [ - "auditTenantAccount", - "correlationId", - "reportTenantAccount", - "tenantId", - "createdAt", - "updatedAt" + "auditTenantAccount" ], - "title": "Report - Correlation Record V0", + "title": "License Report - Correlation Record", "type": "object" }, "Report.CorrelationRecordV1": { @@ -1036,14 +1031,6 @@ "user": { "title": "User Principal Records", "type": "object", - "required": [ - "assignedService", - "assignedLicense", - "consumedService", - "llmInferred", - "principalMetadata", - "enhancedData" - ], "description": "Object containing user records, each keyed by user ID. Includes assigned services, licenses, consumed services, inferred attributes, metadata, and enhanced identity data for each user.", "additionalProperties": { "type": "object", @@ -1076,75 +1063,36 @@ "description": "Inferred principal attributes, showing if the account is a service account, frontline worker, temporary worker.", "properties": { "isServiceAccount": { - "description": "The user service account; may be null if not provided.", - "oneOf": [ - { - "type": "boolean", - "description": "Indicates if the account is a service account.", - "examples": [ - true - ] - }, - { - "type": "null", - "description": "No data or unused." - } + "description": "Indicates if the account is a service account.", + "type": [ + "boolean", + "null" ], "examples": [ - { - "isServiceAccount": true - }, - { - "isServiceAccount": null - } + true, + null ] }, "isFrontlineWorker": { - "description": "The user a temporary employee; may be null if not provided.", - "oneOf": [ - { - "type": "boolean", - "description": "Indicates if the user is a frontline worker.", - "examples": [ - true - ] - }, - { - "type": "null", - "description": "No data or unused." - } + "description": "Indicates if the user is a frontline worker.", + "type": [ + "boolean", + "null" ], "examples": [ - { - "isFrontlineWorker": true - }, - { - "isFrontlineWorker": null - } + true, + null ] }, "isTempWorker": { - "description": "The user is a temporary worker; may be bull if not provided.", - "oneOf": [ - { - "type": "boolean", - "description": "Indicates if the user is a temporary worker.", - "examples": [ - true - ] - }, - { - "type": "null", - "description": "No data or unused." - } + "description": "Indicates if the user is a temporary worker.", + "type": [ + "boolean", + "null" ], "examples": [ - { - "isTempWorker": true - }, - { - "isTempWorker": null - } + true, + null ] } }, @@ -1298,12 +1246,6 @@ "device": { "title": "Device Principal Records", "type": "object", - "required": [ - "assignedService", - "assignedLicense", - "consumedService", - "principalMetadata" - ], "description": "Object containing device records, each keyed by device ID. Includes assigned services, licenses, consumed services, and metadata for each device.", "additionalProperties": { "type": "object", From a0eecdb4b2816f3134e759cef15ac6f3c8f34d1b Mon Sep 17 00:00:00 2001 From: Jesse H Date: Wed, 3 Dec 2025 05:14:55 -0600 Subject: [PATCH 09/14] Rename LicenseReport schemas to LicenseReportV0 Updated all references of LicenseReport, LicenseReport.CorrelationRecord, and LicenseReport.LicenseData to LicenseReportV0, LicenseReportV0.CorrelationRecord, and LicenseReportV0.LicenseData in Data-Gateway.json. This change clarifies schema versioning and improves maintainability. --- specs/Data-Gateway.json | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 2f65d5e..56cdf8e 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -437,12 +437,12 @@ "title": "Report - Feature Breakdown", "type": "object" }, - "LicenseReport.CorrelationRecord": { + "LicenseReportV0.CorrelationRecord": { "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", "$ref": "#/components/schemas/Report.CorrelationRecordV0", "title": "License Report - Correlation Record" }, - "LicenseReport.LicenseData": { + "LicenseReportV0.LicenseData": { "type": "object", "properties": { "assignedLicense": { @@ -592,7 +592,7 @@ ], "title": "License Report - License Data" }, - "LicenseReport": { + "LicenseReportV0": { "description": "Completely calculated license report structure that is the result of a complete run.", "examples": [ { @@ -647,11 +647,11 @@ "type": "object" }, "correlation": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + "$ref": "#/components/schemas/LicenseReportV0.CorrelationRecord" }, "licenseData": { "additionalProperties": { - "$ref": "#/components/schemas/LicenseReport.LicenseData" + "$ref": "#/components/schemas/LicenseReportV0.LicenseData" } } }, @@ -2479,7 +2479,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } } @@ -2545,7 +2545,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } }, @@ -2611,7 +2611,7 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + "$ref": "#/components/schemas/LicenseReportV0.CorrelationRecord" }, "examples": [ [ @@ -2698,7 +2698,7 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + "$ref": "#/components/schemas/LicenseReportV0.CorrelationRecord" }, "examples": [ [ @@ -2811,7 +2811,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } }, @@ -2933,7 +2933,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } }, From b137354ca1c947b1ed094d283d09cdaf7f0507a7 Mon Sep 17 00:00:00 2001 From: Jesse H Date: Wed, 3 Dec 2025 07:07:32 -0600 Subject: [PATCH 10/14] Expand Architecture Report API examples and schema Added detailed example objects for Architecture Report endpoints and correlation records, updated required fields in the correlation record schema, and removed unused principal assignment schemas. Also moved and clarified endpoint summaries for improved OpenAPI documentation consistency. --- specs/Data-Gateway.json | 597 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 553 insertions(+), 44 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 56cdf8e..8d35c2b 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -1015,7 +1015,13 @@ }, "required": [ "auditTenantAccount", - "reportTenantAccount" + "correlationId", + "createdAt", + "isMigrating", + "reportTenantAccount", + "schemaVersion", + "tenantId", + "updatedAt" ], "title": "Report - Correlation Record V1", "type": "object" @@ -2252,6 +2258,89 @@ "tenantMetadata", "principalData" ], + "examples": [ + { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + ], "title": "Architecture Report V1 - Complete Object" }, "ArchitectureReportV1.CorrelationRecord": { @@ -2314,32 +2403,7 @@ "description": "Contains user and device records included in the architecture report, detailing assigned services, licenses, consumed services, and related metadata for each principal.", "$ref": "#/components/schemas/Report.PrincipalData", "title": "Architecture Report - Principal Data" - }, - "Report.CommonPrincipalAssignment": { - "properties": { - "assignedService": { - "oneOf": [ - { - "$ref": "#/components/schemas/Report.FeatureBreakdown" - }, - { - "type": "integer", - "format": "int32", - "examples": [ - 0 - ] - }, - { - "type": "null" - } - ] - }, - "assignedLicense": [], - "consumedService": {} - } - }, - "DevicePrincipalAssignment": {}, - "UserPrincipalAssignment": {} + } }, "securitySchemes": { "EntraID": { @@ -6105,14 +6169,99 @@ }, "/Api/V1/ArchitectureReport": { "post": { - "summary": "Submit Architecture Report V1", "description": "Submits an Architecture Report V1 payload to the Architecture Report endpoint.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, `ArchitectureReport.ReadWrite.All` scope (permission).", "operationId": "/Api/V1/ArchitectureReport/Post", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { + "examples": { + "Architecture Report V1": { + "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", + "summary": "Example of license report stored.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + } + }, "schema": { "$ref": "#/components/schemas/ArchitectureReportV1" } @@ -6124,6 +6273,93 @@ "description": "Architecture Report V1 submitted successfully.", "content": { "application/json": { + "examples": { + "Architecture Report V1": { + "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", + "summary": "Example of license report stored.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + } + }, "schema": { "$ref": "#/components/schemas/ArchitectureReportV1" } @@ -6139,12 +6375,12 @@ }, "tags": [ "Architecture Reporting" - ] + ], + "summary": "Submit Architecture Report V1" } }, "/Api/V1/ArchitectureReport/Correlation": { "get": { - "summary": "Get Correlation Records", "description": "Retrieves the list of correlation records for the authenticated tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", "operationId": "/Api/V1/ArchitectureReport/Correlation/Get", "parameters": [ @@ -6160,11 +6396,64 @@ "description": "A list of correlation records.", "content": { "application/json": { + "examples": { + "Example Correlation Records": { + "description": "Sample list of correlation records for the current authenticated tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", + "createdAt": "2023-12-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + } + }, "schema": { - "type": "array", + "examples": [ + [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", + "createdAt": "2023-12-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + ], "items": { - "$ref": "#/components/schemas/Report.CorrelationRecordV1" - } + "$ref": "#/components/schemas/ArchitectureReportV1.CorrelationRecord" + }, + "minItems": 0, + "type": "array" } } } @@ -6178,12 +6467,12 @@ }, "tags": [ "Architecture Reporting" - ] + ], + "summary": "Get Correlation Records" } }, "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}": { "get": { - "summary": "Get Correlation Records by Tenant", "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, or `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}/Get", "parameters": [ @@ -6199,17 +6488,70 @@ ], "responses": { "200": { - "description": "A list of correlation records for the specified tenant.", "content": { "application/json": { + "examples": { + "Example Correlation Records": { + "description": "Sample list of correlation records for the specified tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "e0d101e8-6f1e-40a9-a66f-cad4112c9a59", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + } + }, "schema": { "type": "array", + "minItems": 0, "items": { - "$ref": "#/components/schemas/CorrelationRecordV1" - } + "$ref": "#/components/schemas/ArchitectureReportV1.CorrelationRecord" + }, + "examples": [ + [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "e0d101e8-6f1e-40a9-a66f-cad4112c9a59", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + ] } } - } + }, + "description": "A list of correlation records for the specified tenant." }, "400": { "$ref": "#/components/responses/400" @@ -6218,6 +6560,7 @@ "$ref": "#/components/responses/500" } }, + "summary": "Get Correlation Records by Tenant", "tags": [ "Architecture Reporting" ] @@ -6225,7 +6568,6 @@ }, "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data": { "delete": { - "summary": "Delete Architecture Report Data by Correlation ID", "description": "Deletes the full license report v1 for the specified correlation ID.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data/Delete", "parameters": [ @@ -6244,12 +6586,12 @@ "$ref": "#/components/responses/500" } }, + "summary": "Delete Architecture Report Data by Correlation ID", "tags": [ "Architecture Reporting" ] }, "get": { - "summary": "Retrieve the specified Architecture Report V1 by Correlation ID", "description": "Retrieves the full license report v1 for the specified correlation ID in the authenticated tenant. The license report v1 contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data/Get", "parameters": [ @@ -6262,6 +6604,89 @@ "description": "The architecture report data for the specified correlation ID.", "content": { "application/json": { + "examples": { + "Example Architecture Report V1": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + }, "schema": { "$ref": "#/components/schemas/ArchitectureReportV1" } @@ -6275,6 +6700,7 @@ "$ref": "#/components/responses/500" } }, + "summary": "Retrieve the specified Architecture Report V1 by Correlation ID", "tags": [ "Architecture Reporting" ] @@ -6326,14 +6752,97 @@ ], "responses": { "200": { - "description": "The architecture report data for the specified correlation ID and tenant ID.", "content": { "application/json": { + "examples": { + "Architecture Report V1": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + }, "schema": { "$ref": "#/components/schemas/ArchitectureReportV1" } } - } + }, + "description": "The architecture report data for the specified correlation ID and tenant ID." }, "400": { "$ref": "#/components/responses/400" From 78886157f1479db1355c8ae9a0547dcc474b50e2 Mon Sep 17 00:00:00 2001 From: Jesse H Date: Wed, 3 Dec 2025 08:28:00 -0600 Subject: [PATCH 11/14] Update required fields for correlation record schema Reduced the required fields in the 'Report - Correlation Record V1' schema to only 'auditTenantAccount'. Updated example objects to match the new schema requirements by removing other previously required fields. Jagdish helped :) --- specs/Data-Gateway.json | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 8d35c2b..8fb1c73 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -1014,14 +1014,7 @@ } }, "required": [ - "auditTenantAccount", - "correlationId", - "createdAt", - "isMigrating", - "reportTenantAccount", - "schemaVersion", - "tenantId", - "updatedAt" + "auditTenantAccount" ], "title": "Report - Correlation Record V1", "type": "object" @@ -3072,8 +3065,7 @@ } ], "correlation": { - "auditTenantAccount": "user@example.com", - "reportTenantAccount": "user@example.com" + "auditTenantAccount": "user@example.com" }, "principalData": { "user": { @@ -6181,14 +6173,7 @@ "summary": "Example of license report stored.", "value": { "correlation": { - "auditTenantAccount": "user@example.com", - "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "createdAt": "2023-11-19T10:00:00.000Z", - "isMigrating": false, - "reportTenantAccount": "user@example.com", - "schemaVersion": 1, - "tenantId": "123e4567-e89b-12d3-a456-426614174000", - "updatedAt": "2023-11-19T10:05:00.000Z" + "auditTenantAccount": "user@example.com" }, "principalData": { "user": { From 15a6304fbb0ebf7acecb0c3b6121992a782364bf Mon Sep 17 00:00:00 2001 From: Jesse H Date: Thu, 4 Dec 2025 05:19:36 -0600 Subject: [PATCH 12/14] Update Architecture Report schema and endpoint docs Added 'schemaVersion' field to ArchitectureReportV1.TenantMetadata and updated its title. Revised several endpoint descriptions to refer to 'architecture report' instead of 'license report'. Standardized operationId path parameters to use colon notation for consistency. --- specs/Data-Gateway.json | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 8fb1c73..a6c156d 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2244,6 +2244,14 @@ }, "tenantMetadata": { "$ref": "#/components/schemas/ArchitectureReportV1.TenantMetadata" + }, + "schemaVersion": { + "type": "integer", + "format": "int32", + "description": "Version number of the license report schema.", + "examples": [ + 1 + ] } }, "required": [ @@ -2390,7 +2398,8 @@ "totalGuestCount", "totalMemberCount", "totalUserCount" - ] + ], + "title": "Architecture Report V1 - Tenant Metadata" }, "ArchitectureReport.PrincipalData": { "description": "Contains user and device records included in the architecture report, detailing assigned services, licenses, consumed services, and related metadata for each principal.", @@ -6161,7 +6170,7 @@ }, "/Api/V1/ArchitectureReport": { "post": { - "description": "Submits an Architecture Report V1 payload to the Architecture Report endpoint.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, `ArchitectureReport.ReadWrite.All` scope (permission).", + "description": "Stores the results of an Architecture report.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, `ArchitectureReport.ReadWrite.All` scope (permission).", "operationId": "/Api/V1/ArchitectureReport/Post", "requestBody": { "required": true, @@ -6459,7 +6468,7 @@ "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}": { "get": { "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, or `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}/Get", + "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/:tenantId/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" @@ -6553,8 +6562,8 @@ }, "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data": { "delete": { - "description": "Deletes the full license report v1 for the specified correlation ID.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data/Delete", + "description": "Deletes the full architecture report v1 for the specified correlation ID.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Data/Delete", "parameters": [ { "$ref": "#/components/parameters/correlationId" @@ -6577,8 +6586,8 @@ ] }, "get": { - "description": "Retrieves the full license report v1 for the specified correlation ID in the authenticated tenant. The license report v1 contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data/Get", + "description": "Retrieves the full architecture report v1 for the specified correlation ID in the authenticated tenant. The architecture report v1 contains all of the tenant metadata and user/device data with the required correlation data.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Data/Get", "parameters": [ { "$ref": "#/components/parameters/correlationId" @@ -6695,7 +6704,7 @@ "delete": { "summary": "Delete the specified Architecture Report V1 for specified tenant", "description": "Deletes the full architecture report v1 for the specified correlation ID and tenant.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data/Delete", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Tenant/:tenantId/Data/Delete", "parameters": [ { "$ref": "#/components/parameters/correlationId", @@ -6724,7 +6733,7 @@ "get": { "summary": "Get Architecture Report v1 Data by Correlation ID and Tenant ID", "description": "Retrieves the architecture report data associated with the specified correlation ID and tenant ID.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", - "operationId": "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data/Get", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Tenant/:tenantId/Data/Get", "parameters": [ { "$ref": "#/components/parameters/correlationId", From 8f8763a7742288f6db69aa8aace853f7085d906d Mon Sep 17 00:00:00 2001 From: Jesse H Date: Thu, 4 Dec 2025 07:09:16 -0600 Subject: [PATCH 13/14] Remove redundant CorrelationRecord schema references - Eliminated duplicate LicenseReportV0.CorrelationRecord and ArchitectureReportV1.CorrelationRecord schema definitions. - Updated all references to use the shared Report.CorrelationRecordV0 and Report.CorrelationRecordV1 schemas directly for consistency and maintainability. --- specs/Data-Gateway.json | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index a6c156d..1b9f97e 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -437,11 +437,6 @@ "title": "Report - Feature Breakdown", "type": "object" }, - "LicenseReportV0.CorrelationRecord": { - "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", - "$ref": "#/components/schemas/Report.CorrelationRecordV0", - "title": "License Report - Correlation Record" - }, "LicenseReportV0.LicenseData": { "type": "object", "properties": { @@ -647,7 +642,7 @@ "type": "object" }, "correlation": { - "$ref": "#/components/schemas/LicenseReportV0.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV0" }, "licenseData": { "additionalProperties": { @@ -2237,7 +2232,7 @@ "type": "object", "properties": { "correlation": { - "$ref": "#/components/schemas/ArchitectureReportV1.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV1" }, "principalData": { "$ref": "#/components/schemas/ArchitectureReport.PrincipalData" @@ -2344,11 +2339,6 @@ ], "title": "Architecture Report V1 - Complete Object" }, - "ArchitectureReportV1.CorrelationRecord": { - "$ref": "#/components/schemas/Report.CorrelationRecordV1", - "description": "Metadata that describes the execution session (run) that is used to tie/relate architecture report versions together.", - "title": "Architecture Report V1 - CorrelationRecord" - }, "ArchitectureReportV1.TenantMetadata": { "description": "This is the the tenant data calculated for the architecture report", "examples": [ @@ -2677,7 +2667,7 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/LicenseReportV0.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV0" }, "examples": [ [ @@ -2764,7 +2754,7 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/LicenseReportV0.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV0" }, "examples": [ [ @@ -6444,7 +6434,7 @@ ] ], "items": { - "$ref": "#/components/schemas/ArchitectureReportV1.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV1" }, "minItems": 0, "type": "array" From 24d96e1856e53628e4781df4a5c1365540a9ea7f Mon Sep 17 00:00:00 2001 From: Jesse H Date: Thu, 4 Dec 2025 07:20:26 -0600 Subject: [PATCH 14/14] Add schemaVersion to required fields in spec Updated the Data-Gateway.json specification to include 'schemaVersion' as a required field alongside 'correlation', 'tenantMetadata', and 'principalData'. --- specs/Data-Gateway.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 1b9f97e..b76f6ee 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2252,7 +2252,8 @@ "required": [ "correlation", "tenantMetadata", - "principalData" + "principalData", + "schemaVersion" ], "examples": [ {