Address review feedback on NFS access point OpenAPI spec.

Align models and examples with sharesvc behavior: fix delete action status,
document validation constraints, add access_points to share responses, dedupe
the action schema, and wire get/list responses to shared model files.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sgupta832

specification/resources/nfs/models/access_point_action_response.yml

@@ -5,49 +5,7 @@ properties:
   access_point:
     $ref: "access_point_response.yml"
   action:
-    type: object
-    description: The action that was submitted for the access point mutation.
-    properties:
-      id:
-        type: string
-        description: The unique identifier of the action.
-        example: "1"
-      region_slug:
-        type: string
-        description: The DigitalOcean region slug where the resource is located.
-        example: "atl1"
-      resource_id:
-        type: string
-        format: uuid
-        description: The unique identifier of the resource on which the action is being performed.
-        example: "a1b2c3d4-e5f6-4a5b-9c8d-1e2f3a4b5c6d"
-      resource_type:
-        type: string
-        enum: ["network_file_share"]
-        description: The type of resource on which the action is being performed.
-        example: "network_file_share"
-      started_at:
-        type: string
-        format: date-time
-        description: The timestamp when the action was started.
-        example: "2025-10-14T11:55:31.615157397Z"
-      status:
-        type: string
-        enum: ["in-progress", "completed", "errored"]
-        description: The current status of the action.
-        example: "in-progress"
-      type:
-        type: string
-        description: The type of action being performed. Access point mutations use CREATE_ACCESS_POINT and DELETE_ACCESS_POINT.
-        example: "CREATE_ACCESS_POINT"
-    required:
-      - region_slug
-      - resource_id
-      - resource_type
-      - started_at
-      - status
-      - type
+    $ref: "nfs_action.yml"
 required:
   - access_point
   - action
-

specification/resources/nfs/models/access_point_get_response.yml

@@ -0,0 +1,8 @@
+---
+type: object
+description: Response containing a single access point.
+properties:
+  access_point:
+    $ref: "access_point_response.yml"
+required:
+  - access_point

specification/resources/nfs/models/access_point_list_response.yml

@@ -7,15 +7,5 @@ properties:
     items:
       $ref: "access_point_response.yml"
     description: Array of access point objects.
-    example:
-      - id: "a1b2c3d4-e5f6-4a5b-9c8d-1e2f3a4b5c6d"
-        name: "my-access-point"
-        share_id: "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
-        path: "/exports/data"
-        status: "ACCESS_POINT_ACTIVE"
-        is_default: false
-        created_at: "2023-01-01T00:00:00Z"
-        updated_at: "2023-01-01T01:00:00Z"
 required:
   - access_points
-

specification/resources/nfs/models/access_point_request.yml

@@ -4,12 +4,20 @@ description: Payload for creating a new access point on a share.
 properties:
   name:
     type: string
-    description: The name for the access point. Must be unique per share.
-    example: "my-access-point"
+    description: |
+      The name for the access point. Must be unique per share. Must be 2–63
+      characters and match `^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]$`.
+      The name `default` is reserved (case-insensitive) for the implicit default
+      access point created with each share.
+    example: "team-a"
   path:
     type: string
-    description: The export sub-path. Must start with "/" and cannot be "/".
-    example: "/exports/data"
+    description: |
+      The export sub-path. Must start with `/`, must not be exactly `/` (reserved
+      for the default access point), must be at most 1024 characters, may contain
+      only alphanumerics, `-`, `_`, `.`, and `/`, and must not contain `..` path
+      segments.
+    example: "/team-a"
   access_policy:
     $ref: "access_policy.yml"
   vpc_id:
@@ -24,4 +32,3 @@ required:
   - name
   - path
   - access_policy
-

specification/resources/nfs/models/access_point_response.yml

@@ -11,7 +11,7 @@ properties:
   name:
     type: string
     description: The human-readable name of the access point. Must be unique per share.
-    example: "my-access-point"
+    example: "team-a"
   share_id:
     type: string
     format: uuid
@@ -20,8 +20,8 @@ properties:
     example: "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
   path:
     type: string
-    description: The export sub-path for this access point. Must start with "/" and cannot be "/".
-    example: "/exports/data"
+    description: The export sub-path for this access point (always starts with `/`).
+    example: "/team-a"
   status:
     type: string
     enum: ["ACCESS_POINT_CREATING", "ACCESS_POINT_ACTIVE", "ACCESS_POINT_FAILED", "ACCESS_POINT_DELETED"]
@@ -68,4 +68,3 @@ required:
   - created_at
   - updated_at
   - is_default
-

specification/resources/nfs/models/access_policy.yml

@@ -1,6 +1,9 @@
 ---
 type: object
-description: Provider-agnostic NFS access policy for an access point.
+description: |
+  Provider-agnostic NFS access policy for an access point. Network CIDRs are
+  managed by attach, detach, and managed-access workflows and are not part of
+  this policy.
 properties:
   anonuid:
     type: integer
@@ -14,9 +17,9 @@ properties:
     type: array
     items:
       type: string
-      enum: ["NFS", "NFS4"]
+      enum: ["NFS4", "NFS"]
     description: Allowed NFS protocols for this export.
-    example: ["NFS4"]
+    example: ["NFS4", "NFS"]
   squash_config:
     type: string
     enum: ["NO_SQUASH", "ROOT_SQUASH", "ALL_SQUASH"]
@@ -25,11 +28,10 @@ properties:
   identity_enforcement_enabled:
     type: boolean
     description: Whether identity enforcement is enabled for this export.
-    example: true
+    example: false
 required:
   - anonuid
   - anongid
   - protocols
   - squash_config
   - identity_enforcement_enabled
-

specification/resources/nfs/models/nfs_action.yml

@@ -0,0 +1,45 @@
+---
+type: object
+description: The action that was submitted.
+properties:
+  id:
+    type: string
+    description: The unique identifier of the action.
+    example: "1"
+  region_slug:
+    type: string
+    description: The DigitalOcean region slug where the resource is located.
+    example: "atl1"
+  resource_id:
+    type: string
+    format: uuid
+    description: The unique identifier of the resource on which the action is being performed.
+    example: "a1b2c3d4-e5f6-4a5b-9c8d-1e2f3a4b5c6d"
+  resource_type:
+    type: string
+    enum: ["network_file_share", "network_file_share_snapshot"]
+    description: The type of resource on which the action is being performed.
+    example: "network_file_share"
+  started_at:
+    type: string
+    format: date-time
+    description: The timestamp when the action was started.
+    example: "2025-10-14T11:55:31.615157397Z"
+  status:
+    type: string
+    enum: ["in-progress", "completed", "errored"]
+    description: The current status of the action.
+    example: "in-progress"
+  type:
+    type: string
+    description: |
+      The type of action being performed. Share actions use values such as resize
+      and snapshot. Access point mutations use CREATE_ACCESS_POINT and DELETE_ACCESS_POINT.
+    example: "CREATE_ACCESS_POINT"
+required:
+  - region_slug
+  - resource_id
+  - resource_type
+  - started_at
+  - status
+  - type

specification/resources/nfs/models/nfs_actions_response.yml

@@ -3,43 +3,6 @@ description: Action response of an NFS share.
 
 properties:
   action:
-    type: object
-    description: The action that was submitted.
-    properties:
-      region_slug:
-        type: string
-        description: The DigitalOcean region slug where the resource is located.
-        example: "atl1"
-      resource_id:
-        type: string
-        format: uuid
-        description: The unique identifier of the resource on which the action is being performed.
-        example: "b5eb9e60-6750-4f3f-90b6-8296966eaf35"
-      resource_type:
-        type: string
-        enum: ["network_file_share", "network_file_share_snapshot"]
-        description: The type of resource on which the action is being performed.
-        example: "network_file_share"
-      started_at:
-        type: string
-        format: date-time
-        description: The timestamp when the action was started.
-        example: "2025-10-14T11:55:31.615157397Z"
-      status:
-        type: string
-        enum: ["in-progress", "completed", "errored"]
-        description: The current status of the action.
-        example: "in-progress"
-      type:
-        type: string
-        description: The type of action being performed.
-        example: "resize"
-    required:
-      - region_slug
-      - resource_id
-      - resource_type
-      - started_at
-      - status
-      - type
+    $ref: "nfs_action.yml"
 required:
   - action

specification/resources/nfs/models/nfs_response.yml

@@ -44,6 +44,11 @@ properties:
     type: string
     description: The host IP of the NFS server that will be accessible from the associated VPC
     example: "10.128.32.2"
+  access_points:
+    type: array
+    items:
+      $ref: 'access_point_response.yml'
+    description: Access points configured on this share. The default access point is returned first.
 required:
   - id
   - name

specification/resources/nfs/nfs_access_point_create.yml

@@ -8,6 +8,10 @@ description: |
 
   A successful request will return the newly created access point and an action object.
 
+  The parent share must be in `ACTIVE` or `INACTIVE` status. Validation failures and
+  precondition errors (such as an ineligible share state) return `400 Bad Request`.
+  Duplicate name or path conflicts return `409 Conflict`.
+
 tags:
   - NFS
 
@@ -30,8 +34,8 @@ requestBody:
       examples:
         Basic Access Point:
           value:
-            name: "my-access-point"
-            path: "/exports/data"
+            name: "team-a"
+            path: "/team-a"
             access_policy:
               anonuid: 65534
               anongid: 65534
@@ -52,6 +56,9 @@ responses:
   '404':
     $ref: '../../shared/responses/not_found.yml'
 
+  '409':
+    $ref: '../../shared/responses/conflict.yml'
+
   '429':
     $ref: '../../shared/responses/too_many_requests.yml'
 
@@ -64,4 +71,3 @@ responses:
 security:
   - bearer_auth:
       - "nfs:create"
-