fix!: make OP required in nested payload discriminated union

Author: qwuide

docs/guide/adapters/standard-adapter/writing.md

@@ -35,38 +35,32 @@ For association configuration, see [Associations](../../representations/associat
 
 ### Create
 
-New records have no `id`:
-
 ```json
 {
   "invoice": {
     "number": "INV-001",
     "items": [
-      { "description": "Consulting" },
-      { "description": "Development" }
+      { "OP": "create", "description": "Consulting" },
+      { "OP": "create", "description": "Development" }
     ]
   }
 }
 ```
 
 ### Update
 
-Existing records include `id`:
-
 ```json
 {
   "invoice": {
     "items": [
-      { "id": "5", "description": "Updated item" }
+      { "OP": "update", "id": "5", "description": "Updated item" }
     ]
   }
 }
 ```
 
 ### Delete
 
-Include `id` and `OP: "delete"`:
-
 ```json
 {
   "invoice": {
@@ -87,8 +81,8 @@ Combine operations in one request:
 {
   "invoice": {
     "items": [
-      { "id": "5", "description": "Updated" },
-      { "description": "New item" },
+      { "OP": "update", "id": "5", "description": "Updated" },
+      { "OP": "create", "description": "New item" },
       { "OP": "delete", "id": "3" }
     ]
   }
@@ -104,9 +98,10 @@ Nesting can go to any depth:
   "invoice": {
     "items": [
       {
+        "OP": "create",
         "description": "Consulting",
         "adjustments": [
-          { "amount": "10.00" }
+          { "OP": "create", "amount": "10.00" }
         ]
       }
     ]
@@ -120,18 +115,18 @@ TypeScript payloads use a discriminated union with `OP` as the discriminator:
 
 ```typescript
 interface ItemNestedCreatePayload {
-  OP?: 'create';
+  OP: 'create';
   description: string;
 }
 
 interface ItemNestedUpdatePayload {
-  OP?: 'update';
+  OP: 'update';
   id?: string;
   description?: string;
 }
 
 interface ItemNestedDeletePayload {
-  OP?: 'delete';
+  OP: 'delete';
   id: string;
 }
 
@@ -141,7 +136,7 @@ type ItemNestedPayload =
   | ItemNestedDeletePayload;
 ```
 
-`OP` is optional on all variants. When omitted, the adapter infers the operation: records without `id` are created, records with `id` are updated.
+`OP` is the discriminator for the union. The adapter uses it to determine the operation for each nested record.
 
 ## Single Table Inheritance
 

docs/guide/sorbus.md

@@ -130,10 +130,12 @@ const { invoice } = await api.invoices.update({
   invoice: {
     items: [
       {
+        OP: 'update',
         id: '5',
         description: 'Updated item',
       },
       {
+        OP: 'create',
         description: 'New item',
         quantity: 1,
         rate: 100,
@@ -147,7 +149,7 @@ const { invoice } = await api.invoices.update({
 });
 ```
 
-No `id` means create. With `id` means update. `OP: 'delete'` with `id` means delete. All in one request, all typed.
+`OP` determines the operation: `'create'`, `'update'`, or `'delete'`.
 
 ## Error Handling
 

lib/apiwork/adapter/standard/capability/writing/contract_builder.rb

@@ -90,7 +90,7 @@ def build_nested_payload(action_name)
               writable = action_name != :delete
 
               object(type_name) do |object|
-                object.literal(Constants::OP, optional: true, value: action_name.to_s)
+                object.literal(Constants::OP, value: action_name.to_s)
                 object.param(:id, optional: action_name != :delete, type: primary_key_type) unless action_name == :create
 
                 next unless writable

spec/integration/adapter/standard/capability/writing/nested_attributes_spec.rb

@@ -38,7 +38,7 @@
             params: {
               invoice: {
                 items: [
-                  { description: 'Updated consulting', id: item1.id, invoice_id: invoice1.id, quantity: 20 },
+                  { OP: 'update', description: 'Updated consulting', id: item1.id, invoice_id: invoice1.id, quantity: 20 },
                 ],
               },
             }
@@ -72,7 +72,7 @@
             params: {
               invoice: {
                 items: [
-                  { description: 'Updated consulting', id: item1.id, invoice_id: invoice1.id, quantity: 20 },
+                  { OP: 'update', description: 'Updated consulting', id: item1.id, invoice_id: invoice1.id, quantity: 20 },
                   { OP: 'delete', id: item2.id },
                   { OP: 'create',
                     description: 'Support contract',

spec/integration/adapter/standard/capability/writing/types_spec.rb

@@ -100,7 +100,6 @@
 
       expect(param.type).to eq(:literal)
       expect(param.value).to eq('create')
-      expect(param.optional?).to be(true)
     end
 
     it 'does not include id' do

spec/integration/adapter/standard/validation_spec.rb

@@ -125,7 +125,7 @@
              params: {
                invoice: {
                  customer_id: customer.id,
-                 items: [{ description: '' }],
+                 items: [{ OP: 'create', description: '', invoice_id: 0, quantity: 1, unit_price: 100 }],
                  number: 'INV-001',
                },
              }