Bring domains and isolation segments to parity with the v3 reference …

docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml

@@ -9,31 +9,53 @@ content:
       properties:
         name:
           type: string
-          description: Name of the domain
+          description: Name of the domain; must be unique (case-insensitive)
         internal:
           type: boolean
-          description: Whether the domain is used for internal (container-to-container) traffic
+          default: false
+          description: Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic
         router_group:
           type: object
           properties:
             guid:
               type: string
               format: uuid
-          description: 'The desired router group guid.  _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+              description: The desired router group guid
+          description: 'The desired router group. _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+        enforce_route_policies:
+          type: boolean
+          default: false
+          description: When `true`, GoRouter enforces route policies for routes on this domain using mutual TLS (mTLS). Set at creation only; cannot be changed on update. Cannot be used with internal domains
+        route_policies_scope:
+          type: string
+          enum:
+            - any
+            - org
+            - space
+          description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
         relationships:
           type: object
           properties:
             organization:
               $ref: ../schemas/RelationshipToOne.yaml
-              description: A relationship to the organization the domain will be scoped to;  _note cannot be used when `internal` is set to `true` or domain is associated with a router group_
+              description: 'A relationship to the organization the domain will be scoped to; _note: cannot be used when `internal` is set to `true` or domain is associated with a router group_'
             shared_organizations:
               $ref: ../schemas/RelationshipToMany.yaml
-              description: A relationship to organizations the domain will be shared with  _Note cannot be used without an organization relationship_
+              description: 'A relationship to organizations the domain will be shared with. _Note: cannot be used without an organization relationship_'
+          description: Relationships to the organization the domain will be scoped to and the organizations the domain will be shared with
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the domain
     examples:
       default:
         summary: default
         value:
           name: example.com
           internal: false
+      identityAwareDomain:
+        summary: Identity-aware domain
+        value:
+          name: apps.identity
+          internal: false
+          enforce_route_policies: true
+          route_policies_scope: org

docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml

@@ -7,4 +7,14 @@ content:
       properties:
         metadata:
           $ref: '../schemas/Metadata.yaml'
+          description: Labels and annotations applied to the domain
       description: Request schema for updating a domain
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              key: value
+            annotations:
+              note: detailed information

docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml

@@ -1,14 +1,16 @@
 description: Isolation segment to create
+required: true
 content:
   application/json:
     schema:
       type: object
       properties:
         name:
           type: string
-          description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness
+          description: Name of the isolation segment; must be unique (case-insensitive)
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the isolation segment
       required:
         - name
     examples:

docs/openapi/apis/cf/latest/components/schemas/Domain.yaml

@@ -9,14 +9,15 @@ allOf:
         type: boolean
         description: Whether the domain is used for internal (container-to-container) traffic
       router_group:
-        type: 
+        type:
           - object
           - 'null'
         properties:
           guid:
             type: string
             format: uuid
-        description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
+            description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
+        description: The router group the domain routes `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
       supported_protocols:
         type: array
         items:
@@ -25,10 +26,29 @@ allOf:
             - http
             - tcp
         description: Available protocols for routes using the domain, currently `http` and `tcp`
+      enforce_route_policies:
+        type: boolean
+        description: When `true`, GoRouter enforces route policies for routes on this domain. This field only appears in the response when set to `true`. Set at creation only; cannot be changed on update
+      route_policies_scope:
+        type: string
+        enum:
+          - any
+          - org
+          - space
+        description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. This field only appears when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
       relationships:
-        $ref: './Relationships.yaml'
+        type: object
+        properties:
+          organization:
+            $ref: './RelationshipToOne.yaml'
+            description: The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available
+          shared_organizations:
+            $ref: './RelationshipToMany.yaml'
+            description: Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to
+        description: Relationships to the organization the domain is scoped to and the organizations the domain is shared with
       metadata:
         $ref: './Metadata.yaml'
+        description: Labels and annotations applied to the domain
       links:
         type: object
         properties:
@@ -37,15 +57,18 @@ allOf:
             description: The URL to get this domain
           organization:
             $ref: './Link.yaml'
-            description: The URL to get the organization for this domain
+            description: The URL to get the organization this domain is scoped to; only present for organization-scoped domains
           route_reservations:
             $ref: './Link.yaml'
-            description: The URL to get the route reservations for this domain
+            description: The URL to check which routes are reserved for this domain
           shared_organizations:
             $ref: './Link.yaml'
-            description: The URL to get the shared organizations for this domain
+            description: The URL to get the organizations this domain is shared with; only present for organization-scoped domains
           router_group:
             $ref: './Link.yaml'
-            description: The URL to get the router group for this domain
-description: |
-  A domain is a fully qualified domain name that is used for application routes. A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.
+            description: The URL to get the router group for this domain; only present for domains associated with a router group
+        description: Links to related resources
+description: |-
+  Domains represent a [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) that is used for application routes.
+
+  A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.

docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml

@@ -2,7 +2,10 @@ type: object
 properties:
   pagination:
     $ref: './Pagination.yaml'
+    description: Pagination information for the list of domains
   resources:
     type: array
     items:
       $ref: './Domain.yaml'
+    description: List of domains
+description: A paginated list of domains

docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml

@@ -4,9 +4,10 @@ allOf:
   - properties:
       name:
         type: string
-        description: The name of the isolation segment
+        description: Name of the isolation segment
       metadata:
         $ref: './Metadata.yaml'
+        description: Labels and annotations on the isolation segment
       links:
         type: object
         properties:
@@ -15,5 +16,6 @@ allOf:
             description: The URL to get this isolation segment
           organizations:
             $ref: './Link.yaml'
-            description: The URL to get the organizations for this isolation segment
-description: An isolation segment provides a dedicated pool of compute resources for an organization or space.
+            description: The URL to get the organizations entitled to this isolation segment
+        description: Links to related resources
+description: Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.

docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml

@@ -2,7 +2,10 @@ type: object
 properties:
   pagination:
     $ref: './Pagination.yaml'
+    description: Pagination information for the list of isolation segments
   resources:
     type: array
     items:
       $ref: './IsolationSegment.yaml'
+    description: List of isolation segments
+description: A paginated list of isolation segments