From 99a223c76a677831809b08d4ca2f1f390173a935 Mon Sep 17 00:00:00 2001 From: Cody Lundie Date: Mon, 29 Jun 2026 17:14:24 -0400 Subject: [PATCH] fix: clear release-review Spectral warnings (#162) - S-011: add missing property/example descriptions; lift nested allOf descriptions to the property level (createdAt, modifiedAt, expiration, atTime, selectedProtocol, selectedType, bootstrappingInfo) - S-015: rename schema UUID -> Uuid (PascalCase) and update all $refs - S-030: move create-only properties into the allOf branch so the required list has no sibling properties (TrustDomainCreate, TrustDomainDeviceCreate) - S-031: add descriptions to capability array items --- code/modules/NAM_Common.yaml | 29 ++++---- .../NetworkAccessDevices.yaml | 2 +- .../RebootRequests/RebootRequests.yaml | 16 +++-- code/modules/Services/ServiceSites.yaml | 3 +- code/modules/Services/Services.yaml | 2 +- .../TrustDomainDevices.yaml | 69 ++++++++++--------- .../TrustDomains/TrustDomainCapabilities.yaml | 2 + code/modules/TrustDomains/TrustDomains.yaml | 23 ++++--- 8 files changed, 80 insertions(+), 66 deletions(-) diff --git a/code/modules/NAM_Common.yaml b/code/modules/NAM_Common.yaml index c528442..c4a5d88 100644 --- a/code/modules/NAM_Common.yaml +++ b/code/modules/NAM_Common.yaml @@ -178,7 +178,8 @@ components: properties: id: allOf: - - $ref: "#/components/schemas/UUID" + - $ref: "#/components/schemas/Uuid" + description: Unique identifier of the resource. readOnly: true required: - id @@ -190,14 +191,14 @@ components: createdAt: allOf: - $ref: "#/components/schemas/DateTime" - - description: | - The creation date and time of the trust domain. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - - readOnly: true + description: | + The creation date and time of the resource. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + readOnly: true createdBy: allOf: - - $ref: "#/components/schemas/UUID" + - $ref: "#/components/schemas/Uuid" description: | The ID of the user or system that created this resource. example: "550e8400-e29b-41d4-a716-446655440000" @@ -205,21 +206,21 @@ components: modifiedAt: allOf: - $ref: "#/components/schemas/DateTime" - - description: | - The last update date and time of the trust domain. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - - readOnly: true + description: | + The last update date and time of the resource. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + readOnly: true modifiedBy: allOf: - - $ref: "#/components/schemas/UUID" + - $ref: "#/components/schemas/Uuid" description: | The ID of the user or system that modified this resource. example: "660e8400-e29b-41d4-a716-446655440000" readOnly: true description: A generic schema for resources with unique identifiers and audit fields. - UUID: + Uuid: type: string format: uuid pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' diff --git a/code/modules/NetworkAccessDevices/NetworkAccessDevices.yaml b/code/modules/NetworkAccessDevices/NetworkAccessDevices.yaml index b39c317..5ec38af 100644 --- a/code/modules/NetworkAccessDevices/NetworkAccessDevices.yaml +++ b/code/modules/NetworkAccessDevices/NetworkAccessDevices.yaml @@ -42,7 +42,7 @@ components: Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. required: true schema: - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + $ref: "../NAM_Common.yaml#/components/schemas/Uuid" schemas: NetworkAccessDevice: description: | diff --git a/code/modules/RebootRequests/RebootRequests.yaml b/code/modules/RebootRequests/RebootRequests.yaml index a725ef6..1eb4a89 100644 --- a/code/modules/RebootRequests/RebootRequests.yaml +++ b/code/modules/RebootRequests/RebootRequests.yaml @@ -19,7 +19,7 @@ components: in: path required: true schema: - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + $ref: "../NAM_Common.yaml#/components/schemas/Uuid" description: ID of the Reboot Request. If the Reboot Request exists but the caller lacks permission to access it, the API returns 403. schemas: @@ -35,11 +35,11 @@ components: atTime: allOf: - $ref: "../NAM_Common.yaml#/components/schemas/DateTime" - - description: | - The date and time to reboot the device. Do not include 'atTime' to request immediate reboot. It must - follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or - 2023-07-03T12:27:08.312Z). + description: | + The date and time to reboot the device. Do not include 'atTime' to request immediate reboot. It must + follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or + 2023-07-03T12:27:08.312Z). RebootRequestCreate: description: Represents the creation of a reboot request, including target devices and optional scheduling. If devices is omitted, the provider MAY infer a default device. Inference rules vary by implementation. If inference is unsupported or ambiguous, creation MUST fail. @@ -49,7 +49,7 @@ components: devices: type: array items: - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + $ref: "../NAM_Common.yaml#/components/schemas/Uuid" maxItems: 100 description: >- List of devices to reboot. When undefined, the reboot targets the 'default' device (simple use case that @@ -86,11 +86,13 @@ components: examples: RebootRequestCreateImmediateDefaultDevice: summary: Example of a Reboot Request for immediate reboot + description: Request an immediate reboot of the inferred default device by omitting 'atTime' and 'devices'. value: message: "reboot to correct performance" RebootRequestCreateScheduledMultipleDevices: summary: Example of a Reboot Request for scheduled reboot of multiple devices + description: Request a scheduled reboot of multiple explicitly listed devices at a future 'atTime'. value: message: "Scheduled reboot for maintenance" atTime: *date-time diff --git a/code/modules/Services/ServiceSites.yaml b/code/modules/Services/ServiceSites.yaml index 5406f64..37911e9 100644 --- a/code/modules/Services/ServiceSites.yaml +++ b/code/modules/Services/ServiceSites.yaml @@ -33,7 +33,8 @@ components: properties: id: allOf: - - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + - $ref: "../NAM_Common.yaml#/components/schemas/Uuid" + description: Unique identifier of the service site. readOnly: true name: type: string diff --git a/code/modules/Services/Services.yaml b/code/modules/Services/Services.yaml index 0a0d953..9d981ba 100644 --- a/code/modules/Services/Services.yaml +++ b/code/modules/Services/Services.yaml @@ -44,7 +44,7 @@ components: schemas: ServiceId: allOf: - - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + - $ref: "../NAM_Common.yaml#/components/schemas/Uuid" description: | A unique identifier that represents a service account associated with this resource. diff --git a/code/modules/TrustDomainDevices/TrustDomainDevices.yaml b/code/modules/TrustDomainDevices/TrustDomainDevices.yaml index add7aa2..b9e5d83 100644 --- a/code/modules/TrustDomainDevices/TrustDomainDevices.yaml +++ b/code/modules/TrustDomainDevices/TrustDomainDevices.yaml @@ -47,7 +47,7 @@ components: in: path required: true schema: - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + $ref: "../NAM_Common.yaml#/components/schemas/Uuid" description: | The unique identifier of the Trust Domain Device. If the device exists but the caller lacks permission to access it, the API returns 403. @@ -184,12 +184,12 @@ components: selectedProtocol: allOf: - $ref: "#/components/schemas/BootstrappingProtocol" - - readOnly: true - description: | - The bootstrapping protocol selected by the server for onboarding this - device. Present only in responses. Determined by intersecting the - device's configured protocols with the Trust Domain's capabilities, - respecting protocolPreference ordering if provided. + readOnly: true + description: | + The bootstrapping protocol selected by the server for onboarding this + device. Present only in responses. Determined by intersecting the + device's configured protocols with the Trust Domain's capabilities, + respecting protocolPreference ordering if provided. DPP: $ref: "#/components/schemas/DppBootstrappingConfig" MATTER: @@ -239,11 +239,11 @@ components: selectedType: allOf: - $ref: "#/components/schemas/CredentialType" - - readOnly: true - description: | - The credential type the server selected. Present only in responses. - Determined by matching supportedTypes against the Trust Domain's - access configuration. + readOnly: true + description: | + The credential type the server selected. Present only in responses. + Determined by matching supportedTypes against the Trust Domain's + access configuration. AssignDeviceCredential: type: object @@ -338,39 +338,39 @@ components: bootstrappingInfo: allOf: - $ref: "#/components/schemas/BootstrappingInfo" - - description: | - Provisioning protocol configurations that define how this device can be - onboarded to the Trust Domain. Each property identifies a bootstrapping - protocol and its configuration. A device may support multiple protocols. - Use `protocolPreference` to express the device's preferred protocol ordering - for deterministic server selection. - - **Update Semantics** - - On update (PATCH), the object replaces the previous object entirely when - included. Partial merge semantics are not defined; clients MUST supply the - complete desired configuration for this field. + description: | + Provisioning protocol configurations that define how this device can be + onboarded to the Trust Domain. Each property identifies a bootstrapping + protocol and its configuration. A device may support multiple protocols. + Use `protocolPreference` to express the device's preferred protocol ordering + for deterministic server selection. + + **Update Semantics** + - On update (PATCH), the object replaces the previous object entirely when + included. Partial merge semantics are not defined; clients MUST supply the + complete desired configuration for this field. deviceCredential: $ref: "#/components/schemas/DeviceCredential" TrustDomainDeviceCreate: allOf: - $ref: "#/components/schemas/TrustDomainDeviceUpdate" + - properties: + externalId: + type: string + minLength: 1 + maxLength: 255 + description: | + A manufacturer or user-assigned identifier for the device (e.g., serial number, + model code, or asset tag). This is distinct from the system-generated UUID `id` + and can be used for cross-referencing the device with external systems. + example: "SN-12345-ABCDE" description: | Represents the creation payload for registering a new device to a Trust Domain. Extends TrustDomainDeviceUpdate with additional creation-only fields and required field constraints. required: - deviceName - enabled - properties: - externalId: - type: string - minLength: 1 - maxLength: 255 - description: | - A manufacturer or user-assigned identifier for the device (e.g., serial number, - model code, or asset tag). This is distinct from the system-generated UUID `id` - and can be used for cross-referencing the device with external systems. - example: "SN-12345-ABCDE" TrustDomainDevice: allOf: @@ -430,6 +430,7 @@ components: TrustDomainDeviceCreateIoT: summary: Register an IoT device with DPP bootstrapping and server-generated credential. + description: Registers an IoT device that bootstraps over DPP and requests a server-generated credential. value: deviceName: "Smart Thermostat" externalId: "SN-THERMO-001" @@ -442,12 +443,14 @@ components: TrustDomainDeviceCreateMinimal: summary: Register a device with minimal required fields. + description: Registers a device supplying only the required fields (deviceName and enabled). value: deviceName: "Guest Laptop" enabled: true TrustDomainDeviceCreateMatter: summary: Register a Matter device. + description: Registers a Matter device that bootstraps using Matter onboarding information. value: deviceName: "Smart Light Bulb" externalId: "MATTER-BULB-42" diff --git a/code/modules/TrustDomains/TrustDomainCapabilities.yaml b/code/modules/TrustDomains/TrustDomainCapabilities.yaml index 6d2803b..88f762a 100644 --- a/code/modules/TrustDomains/TrustDomainCapabilities.yaml +++ b/code/modules/TrustDomains/TrustDomainCapabilities.yaml @@ -183,6 +183,7 @@ components: type: array items: type: string + description: A destination address format supported by the egress allowed list policy. enum: ["IP", "FQDN", "CIDR"] maxItems: 3 description: Supported destination address formats @@ -204,6 +205,7 @@ components: type: array items: type: string + description: A Wi-Fi security mode type supported by the API provider. enum: - "WPA2-Personal" - "WPA3-Personal" diff --git a/code/modules/TrustDomains/TrustDomains.yaml b/code/modules/TrustDomains/TrustDomains.yaml index d4af878..5d3dfba 100644 --- a/code/modules/TrustDomains/TrustDomains.yaml +++ b/code/modules/TrustDomains/TrustDomains.yaml @@ -64,7 +64,7 @@ components: in: path required: true schema: - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + $ref: "../NAM_Common.yaml#/components/schemas/Uuid" description: ID of the Trust Domain. If the Trust Domain exists but the caller lacks permission to access it, the API returns 403. schemas: @@ -90,12 +90,12 @@ components: expiration: allOf: - $ref: "../NAM_Common.yaml#/components/schemas/DateTime" - - description: | - The expiration date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + description: | + The expiration date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - If omitted, the trust domain will not automatically expire. + If omitted, the trust domain will not automatically expire. policies: $ref: "../Policy.yaml#/components/schemas/Policies" accessDetails: @@ -140,15 +140,15 @@ components: TrustDomainCreate: allOf: - $ref: "#/components/schemas/TrustDomainUpdate" + - properties: + serviceId: + $ref: "../Services/Services.yaml#/components/schemas/ServiceId" description: Represents the creation of a new trust domain within the network access management system. required: - name - enabled - accessDetails - serviceId - properties: - serviceId: - $ref: "../Services/Services.yaml#/components/schemas/ServiceId" TrustDomain: allOf: @@ -174,6 +174,7 @@ components: TrustDomainCreateWpa2Personal: summary: Create a Trust Domain with WPA2-Personal Wi-Fi access. + description: Creates a Trust Domain with a single WPA2-Personal Wi-Fi access detail that specifies an SSID. value: name: "Primary WiFi Network" description: "Request defines a Trust Domain with WPA2-Personal Wi-Fi access. The request specifies an SSID, implying the SSID is created on the network infrastructure." @@ -184,6 +185,7 @@ components: TrustDomainCreateInferredSsid: summary: Create a Trust Domain with inferred SSID Wi-Fi access. + description: Creates a Trust Domain that omits the SSID, applying access to an existing SSID on the network infrastructure. value: name: "Inferred SSID Network" description: "Request defines a Trust Domain with inferred SSID Wi-Fi access. The request omits the SSID, implying the Trust Domain is applied to an existing SSID on the network infrastructure." @@ -197,6 +199,7 @@ components: TrustDomainCreateEphemeral: summary: Create a Trust Domain with ephemeral access details. + description: Creates a time-limited Trust Domain using an 'expiration' timestamp and a max-devices policy. value: name: "Ephemeral Network" description: "Request defines a Trust Domain with ephemeral access details." @@ -210,6 +213,7 @@ components: TrustDomainCreateThreadStructured: summary: Create a Trust Domain with Thread structured access details. + description: Creates a Trust Domain with a Thread structured access detail. value: name: "Thread Structured Network" description: "Request defines a Trust Domain with Thread structured access details." @@ -220,6 +224,7 @@ components: TrustDomainCreateQoSPolicies: summary: Create a Trust Domain with QoS policies. + description: Creates a Trust Domain with bandwidth QoS policies applied to the domain. value: name: "QoS Policy Network" description: "Request defines a Trust Domain with QoS policies."