fix: keep writeOnly fields out of response documentation (#160)

code/API_definitions/network-access-devices.yaml

@@ -218,6 +218,9 @@ paths:
             application/json:
               schema:
                 $ref: "../modules/NetworkAccessDevices/NetworkAccessDevices.yaml#/components/schemas/NetworkAccessDeviceList"
+              examples:
+                NetworkAccessDeviceListResponse:
+                  $ref: "../modules/NetworkAccessDevices/NetworkAccessDevices.yaml#/components/examples/NetworkAccessDeviceListResponse"
         "400":
           $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
         "401":
@@ -334,6 +337,11 @@ paths:
             application/json:
               schema:
                 $ref: '../modules/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequest'
+              examples:
+                RebootRequestResponseInferred:
+                  $ref: '../modules/RebootRequests/RebootRequests.yaml#/components/examples/RebootRequestResponseInferred'
+                RebootRequestResponseExplicit:
+                  $ref: '../modules/RebootRequests/RebootRequests.yaml#/components/examples/RebootRequestResponseExplicit'
         '400':
           $ref: '../common/CAMARA_common.yaml#/components/responses/Generic400'
         '401':

code/API_definitions/network-access-domains.yaml

@@ -250,6 +250,9 @@ paths:
             application/json:
               schema:
                 $ref: "../modules/Services/Services.yaml#/components/schemas/ServiceList"
+              examples:
+                ServiceListResponse:
+                  $ref: "../modules/Services/Services.yaml#/components/examples/ServiceListResponse"
         "400":
           $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
         "401":
@@ -622,6 +625,8 @@ paths:
                 $ref: '../modules/TrustDomainDevices/TrustDomainDevices.yaml#/components/examples/TrustDomainDeviceCreateMinimal'
               TrustDomainDeviceCreateMatter:
                 $ref: '../modules/TrustDomainDevices/TrustDomainDevices.yaml#/components/examples/TrustDomainDeviceCreateMatter'
+              TrustDomainDeviceCreateAssignCredential:
+                $ref: '../modules/TrustDomainDevices/TrustDomainDevices.yaml#/components/examples/TrustDomainDeviceCreateAssignCredential'
       responses:
         '201':
           headers:

code/modules/AccessDetail.yaml

@@ -1,5 +1,11 @@
 # This file defines the AccessDetail schema model for different network access types.
 # It includes Wi-Fi and Thread access details with various security modes.
+#
+# Examples: property-level only. No object-level `example:` blocks here — several of
+# these schemas carry writeOnly secrets, and an object-level example is printed
+# verbatim into the response pane, defeating the writeOnly filter. Renderers
+# synthesize object samples from the property examples below and honor
+# readOnly/writeOnly while doing so.
 
 components:
   schemas:
@@ -15,7 +21,7 @@
           maxLength: 255
           pattern: "^[\\x20-\\x7E]{8,63}$"
           description: The password for the WPA Personal Wi-Fi network
-          example: &wpa-personal-password "my-password"
+          example: "my-password"
         securityModeType:
           type: string
           enum:
@@ -25,36 +31,30 @@
           description: |
             The security mode type for the WPA Personal Wi-Fi network.
             Leave blank to auto-select.
-          example: &wpa-personal-security-mode-type "WPA3-Personal"
+          example: "WPA3-Personal"
       additionalProperties: false
       required:
         - password
-      example: &wpa-personal
-        password: *wpa-personal-password
-        securityModeType: *wpa-personal-security-mode-type
 
     WpaEnterpriseDetail:
       type: object
       description: WPA Enterprise security mode configuration for Wi-Fi networks.
       properties:
         authServer:
           type: string
           maxLength: 255
           description: The authentication server for the WPA Enterprise Wi-Fi network
-          example: &wpa-enterprise-auth-server "1.2.3.4"
+          example: "1.2.3.4"
         securityModeType:
           type: string
           enum:
             - WPA2-Enterprise
             - WPA3-Enterprise
           description: The security mode type for the WPA Enterprise Wi-Fi network
-          example: &wpa-enterprise-security-mode-type "WPA3-Enterprise"
+          example: "WPA3-Enterprise"
       additionalProperties: false
       required:
         - securityModeType
-      example: &wpa-enterprise
-        authServer: *wpa-enterprise-auth-server
-        securityModeType: *wpa-enterprise-security-mode-type
 
     # Flattened concrete implementations for Wi-Fi
     WiFiWpaPersonalAccessDetail:
@@ -83,15 +83,10 @@
           allOf:
             - $ref: "#/components/schemas/WpaPersonalDetail"
           description: WPA Personal security mode details
-          example: *wpa-personal
       additionalProperties: false
       required:
         - accessType
         - securityMode
-      example: &wifi-wpa-personal-access-detail
-        accessType: "Wi-Fi:WPA_PERSONAL"
-        ssid: *wifi-ssid
-        securityMode: *wpa-personal
 
     WiFiWpaEnterpriseAccessDetail:
       type: object
@@ -119,15 +114,10 @@
           allOf:
             - $ref: "#/components/schemas/WpaEnterpriseDetail"
           description: WPA Enterprise security mode details
-          example: *wpa-enterprise
       additionalProperties: false
       required:
         - accessType
         - securityMode
-      example: &wifi-wpa-enterprise-access-detail
-        accessType: "Wi-Fi:WPA_ENTERPRISE"
-        ssid: *wifi-ssid
-        securityMode: *wpa-enterprise
 
     ThreadStructuredAccessDetail:
       type: object
@@ -158,7 +148,7 @@
           maxLength: 32
           description: The Thread Network Key (32 hex digits)
           example: "dfd34f0f05cad978ec4e32b0413038ff"
         networkName:
           type: string
           minLength: 1
           maxLength: 16
@@ -178,13 +168,6 @@
         - networkKey
         - networkName
         - panId
-      example: &thread-structured-access-detail
-        accessType: "Thread:STRUCTURED"
-        channel: 13
-        extendedPanId: "d63e8e3e495ebbc3"
-        networkKey: "dfd34f0f05cad978ec4e32b0413038ff"
-        networkName: "Spec-Thread-B3AF"
-        panId: "d63e"
 
     ThreadTlvAccessDetail:
       type: object
@@ -196,7 +179,7 @@
           enum:
             - "Thread:TLV"
           example: "Thread:TLV"
         operationalDataset:
           type: string
           maxLength: 255
           description: The Thread network credentials (operational dataset) encoded as a TLV hex string
@@ -205,9 +188,6 @@
       required:
         - accessType
         - operationalDataset
-      example: &thread-tlv-access-detail
-        accessType: "Thread:TLV"
-        operationalDataset: "0e08000000000000010010000102030405060708090a0b0c0d0e0f"
 
     # Single discriminated union with namespaced values
     AccessDetail:
@@ -226,4 +206,3 @@
       required:
         - accessType
       description: Network access details for different network types and variants
-      example: *wifi-wpa-personal-access-detail

code/modules/NAM_Common.yaml

@@ -41,7 +41,7 @@
         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)
-      example: &date-time "2023-07-03T14:27:08.312+02:00"
+      example: "2023-07-03T14:27:08.312+02:00"
 
     PropertyAddress:
       type: object
@@ -50,128 +50,109 @@
         description: TMF673 Geographic Address Management API User Guide v4.0.0
         url: https://www.tmforum.org/resources/specification/tmf673-geographic-address-management-api-user-guide-v4-0-0/
       properties:
         id:
           type: string
           description: The unique identifier for the property address
           minLength: 1
           maxLength: 64
-          example: &property-address-id "address-123"
+          example: "address-123"
         addressLine1:
           type: string
           maxLength: 128
           description: The first line of the address
-          example: &property-address-address-line-1 "123 Main St"
+          example: "123 Main St"
         addressLine2:
           type: string
           maxLength: 128
           description: The second line of the address
-          example: &property-address-address-line-2 "Suite 456"
+          example: "Suite 456"
         streetNr:
           type: string
           maxLength: 64
           description: The street number
-          example: &property-address-street-nr "123"
+          example: "123"
         streetNrSuffix:
           type: string
           maxLength: 64
           description: The suffix for the street number
-          example: &property-address-street-nr-suffix "A"
+          example: "A"
         streetNrLast:
           type: string
           maxLength: 64
           description: The last street number
-          example: &property-address-street-nr-last "125"
+          example: "125"
         streetNrLastSuffix:
           type: string
           maxLength: 64
           description: The suffix for the last street number
-          example: &property-address-street-nr-last-suffix "B"
+          example: "B"
         streetName:
           type: string
           maxLength: 64
           description: The name of the street
-          example: &property-address-street-name "Main"
+          example: "Main"
         subUnitType:
           type: string
           maxLength: 64
           description: The type of sub-unit (e.g., Apartment, Suite)
-          example: &property-address-sub-unit-type "Apartment"
+          example: "Apartment"
         subUnitNr:
           type: string
           maxLength: 64
           description: The number of the sub-unit
-          example: &property-address-sub-unit-nr "A12"
+          example: "A12"
         levelType:
           type: string
           maxLength: 64
           description: The type of level (e.g., Floor, Basement)
-          example: &property-address-level-type "Floor"
+          example: "Floor"
         levelNr:
           type: string
           maxLength: 64
           description: The number of the level
-          example: &property-address-level-nr "3"
+          example: "3"
         buildingName:
           type: string
           maxLength: 64
           description: The name of the building
-          example: &property-address-building-name "Example Building"
+          example: "Example Building"
         privateStreetName:
           type: string
           maxLength: 64
           description: The name of a private street
-          example: &property-address-private-street-name "Private Rd"
+          example: "Private Rd"
         locality:
           type: string
           maxLength: 64
           description: The locality (neighborhood, area)
-          example: &property-address-locality "Example Locality"
+          example: "Example Locality"
         city:
           type: string
           maxLength: 128
           description: The city or town
-          example: &property-address-city "Example State"
+          example: "Example State"
         stateOrProvince:
           type: string
           maxLength: 64
           description: The state or province
-          example: &property-address-state-or-province "EX"
+          example: "EX"
         country:
           type: string
           maxLength: 64
           description: The country
-          example: &property-address-country "United States"
+          example: "United States"
         postCode:
           type: string
           maxLength: 64
           description: The postal code or ZIP code
-          example: &property-address-post-code "12345"
+          example: "12345"
         postCodeExtension:
           type: string
           maxLength: 64
           description: The postal code extension
-          example: &property-address-post-code-extension "6789"
-      example: &property-address
-        id: *property-address-id
-        addressLine1: *property-address-address-line-1
-        addressLine2: *property-address-address-line-2
-        streetNr: *property-address-street-nr
-        streetNrSuffix: *property-address-street-nr-suffix
-        streetNrLast: *property-address-street-nr-last
-        streetNrLastSuffix: *property-address-street-nr-last-suffix
-        streetName: *property-address-street-name
-        subUnitType: *property-address-sub-unit-type
-        subUnitNr: *property-address-sub-unit-nr
-        levelType: *property-address-level-type
-        levelNr: *property-address-level-nr
-        buildingName: *property-address-building-name
-        privateStreetName: *property-address-private-street-name
-        locality: *property-address-locality
-        city: *property-address-city
-        stateOrProvince: *property-address-state-or-province
-        country: *property-address-country
-        postCode: *property-address-post-code
-        postCodeExtension: *property-address-post-code-extension
+          example: "6789"
+      # No object-level example: every property above carries one, and renderers
+      # synthesize the object sample from those.
 
     ResourceIdentifier:
       type: object
@@ -180,6 +161,7 @@
           allOf:
             - $ref: "#/components/schemas/Uuid"
           description: Unique identifier of the resource.
+          example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
           readOnly: true
       required:
         - id
@@ -210,6 +192,7 @@
             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).
+          example: "2023-07-06T09:15:22.104+02:00"
           readOnly: true
         modifiedBy:
           allOf: