Add A ResourceID Component For Record Inputs

openapi/components/parameters/ID.yaml

@@ -0,0 +1,6 @@
+name: id
+in: path
+required: true
+description: ID of the record - a path refuses its URL
+schema:
+  $ref: '#/components/schemas/ResourceID'

openapi/components/parameters/UserID.yaml

@@ -0,0 +1,6 @@
+name: user_id
+in: path
+required: true
+description: ID of the user - a path refuses its URL
+schema:
+  $ref: '#/components/schemas/ResourceID'

openapi/components/schemas/AttachmentUpdatePayload.yaml

@@ -3,8 +3,7 @@ required:
 - url
 properties:
   url:
-    type: string
-    example: https://api.freeagent.com/v2/attachments/1
+    $ref: '#/components/schemas/ResourceID'
   data:
     type: string
     description: Binary data of the file encoded as base64

openapi/components/schemas/BankTransactionExplanationCreatePayload.yaml

@@ -3,14 +3,11 @@ properties:
   attachment:
     $ref: '#/components/schemas/AttachmentPayload'
   bank_account:
-    type: string
-    example: https://api.freeagent.com/v2/bank_accounts/1
+    $ref: '#/components/schemas/ResourceID'
   bank_transaction:
-    type: string
-    example: https://api.freeagent.com/v2/bank_transactions/8
+    $ref: '#/components/schemas/ResourceID'
   category:
-    type: string
-    example: https://api.freeagent.com/v2/categories/285
+    $ref: '#/components/schemas/ResourceID'
   dated_on:
     type: string
     example: 2010-05-01
@@ -21,17 +18,13 @@ properties:
     type: string
     example: '-730.0'
   paid_bill:
-    type: string
-    example: https://api.freeagent.com/v2/bills/123
+    $ref: '#/components/schemas/ResourceID'
   paid_invoice:
-    type: string
-    example: https://api.freeagent.com/v2/invoices/123
+    $ref: '#/components/schemas/ResourceID'
   paid_user:
-    type: string
-    example: https://api.freeagent.com/v2/users/1
+    $ref: '#/components/schemas/ResourceID'
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   rebill_factor:
     type: string
     example: '0.25'

openapi/components/schemas/BankTransactionExplanationUpdatePayload.yaml

@@ -3,20 +3,17 @@ properties:
   attachment:
     $ref: '#/components/schemas/AttachmentPayload'
   category:
-    type: string
-    example: https://api.freeagent.com/v2/categories/285
+    $ref: '#/components/schemas/ResourceID'
   description:
     type: string
     example: Updated description
   gross_value:
     type: string
     example: '-730.0'
   paid_bill:
-    type: string
-    example: https://api.freeagent.com/v2/bills/123
+    $ref: '#/components/schemas/ResourceID'
   paid_user:
-    type: string
-    example: https://api.freeagent.com/v2/users/1
+    $ref: '#/components/schemas/ResourceID'
   sales_tax_rate:
     type: string
     example: '0.0'

openapi/components/schemas/BillCreatePayload.yaml

@@ -6,8 +6,7 @@ required:
 - due_on
 properties:
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/1
+    $ref: '#/components/schemas/ResourceID'
   reference:
     type: string
     example: REF100
@@ -21,8 +20,7 @@ properties:
     type: string
     example: Vehicle purchase
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   recurring:
     $ref: '#/components/schemas/BillRecurringPeriod'
   recurring_end_date:

openapi/components/schemas/BillItemPayload.yaml

@@ -1,16 +1,14 @@
 type: object
 properties:
   url:
-    type: string
-    description: On update, the URL or ID of an existing item to update or remove, or an empty string to add one - FreeAgent rejects an item without it
-    example: https://api.freeagent.com/v2/bill_items/1
+    $ref: '#/components/schemas/ResourceID'
+    description: On update, the existing item to update or remove, or an empty string to add one - FreeAgent rejects an item without it
   _destroy:
     type: integer
     description: Set to 1, with url, to remove the item
     example: 1
   category:
-    type: string
-    example: https://api.freeagent.com/v2/categories/285
+    $ref: '#/components/schemas/ResourceID'
   description:
     type: string
     example: Item description

openapi/components/schemas/BillUpdatePayload.yaml

@@ -1,8 +1,7 @@
 type: object
 properties:
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/1
+    $ref: '#/components/schemas/ResourceID'
   reference:
     type: string
     example: REF100
@@ -17,8 +16,7 @@ properties:
     description: An empty string removes the comments
     example: Annual hosting
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   recurring:
     $ref: '#/components/schemas/BillRecurringPeriod'
   recurring_end_date:

openapi/components/schemas/CreditNoteCreatePayload.yaml

@@ -4,11 +4,9 @@ required:
 - dated_on
 properties:
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/1
+    $ref: '#/components/schemas/ResourceID'
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   dated_on:
     type: string
     example: '2026-10-02'

openapi/components/schemas/CreditNoteItemPayload.yaml

@@ -2,7 +2,7 @@ type: object
 properties:
   id:
     type: string
-    description: ID of an existing item to update or remove - the docs say integer, and a string is accepted too
+    description: ID of an existing item to update or remove, not its URL, which is a 404 - the docs say integer, and a string is accepted too
     example: '1'
   _destroy:
     type: integer

openapi/components/schemas/EstimateCreatePayload.yaml

@@ -5,11 +5,9 @@ required:
 - status
 properties:
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/1
+    $ref: '#/components/schemas/ResourceID'
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   dated_on:
     type: string
     example: '2026-10-02'

openapi/components/schemas/ExpenseCreatePayload.yaml

@@ -6,12 +6,10 @@ required:
 - description
 properties:
   user:
-    type: string
-    example: https://api.freeagent.com/v2/users/1
+    $ref: '#/components/schemas/ResourceID'
   category:
-    type: string
+    $ref: '#/components/schemas/ResourceID'
     description: The Mileage category (249) makes a mileage claim, which takes mileage and vehicle_type in place of gross_value
-    example: https://api.freeagent.com/v2/categories/285
   dated_on:
     type: string
     example: 2026-09-15
@@ -38,8 +36,7 @@ properties:
     type: string
     example: REC-001
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   rebill_type:
     $ref: '#/components/schemas/ExpenseRebillType'
   rebill_factor:

openapi/components/schemas/ExpenseUpdatePayload.yaml

@@ -1,11 +1,9 @@
 type: object
 properties:
   user:
-    type: string
-    example: https://api.freeagent.com/v2/users/1
+    $ref: '#/components/schemas/ResourceID'
   category:
-    type: string
-    example: https://api.freeagent.com/v2/categories/285
+    $ref: '#/components/schemas/ResourceID'
   dated_on:
     type: string
     example: 2026-09-15
@@ -32,8 +30,7 @@ properties:
     description: An empty string removes the receipt reference
     example: REC-001
   project:
-    type: string
-    example: https://api.freeagent.com/v2/projects/1
+    $ref: '#/components/schemas/ResourceID'
   rebill_type:
     $ref: '#/components/schemas/ExpenseRebillType'
   rebill_factor:

openapi/components/schemas/InvoiceCreatePayload.yaml

@@ -4,12 +4,10 @@ properties:
     type: boolean
     example: false
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/:id
+    $ref: '#/components/schemas/ResourceID'
   project:
-    type: string
+    $ref: '#/components/schemas/ResourceID'
     description: Must belong to the contact, or the create is a 422
-    example: https://api.freeagent.com/v2/projects/:id
   include_timeslips:
     type: string
     description: Bills every unbilled timeslip on the project onto the invoice, grouped as named - without a project nothing is billed

openapi/components/schemas/JournalEntryPayload.yaml

@@ -2,17 +2,15 @@ type: object
 additionalProperties: false
 properties:
   url:
-    type: string
-    description: On update, the URL or ID of an existing entry to update or remove - left out, the entry is added
-    example: https://api.freeagent.com/v2/journal_sets/1/journal_entries/1
+    $ref: '#/components/schemas/ResourceID'
+    description: On update, the existing entry to update or remove - left out, the entry is added
   _destroy:
     type: boolean
     description: Set to true, with url, to remove the entry
     example: true
   category:
-    type: string
-    description: The category URL or nominal code - an unknown code is a 400
-    example: https://api.freeagent.com/v2/categories/901
+    $ref: '#/components/schemas/ResourceID'
+    description: The category, whose ID is its nominal code - an unknown code is a 400
   debit_value:
     type: number
     description: Negative for a credit - rounded to two places, and 0 when left out
@@ -21,13 +19,11 @@ properties:
     type: string
     example: Director's capital introduced
   user:
-    type: string
+    $ref: '#/components/schemas/ResourceID'
     description: Needed for user categories such as 901 and 907, or the request is a 404 - ignored on other categories
-    example: https://api.freeagent.com/v2/users/1
   capital_asset_type:
-    type: string
+    $ref: '#/components/schemas/ResourceID'
     description: Needed for capital asset categories 601 to 607, or the request is a 404
-    example: https://api.freeagent.com/v2/capital_asset_types/1
   stock_item:
     type: string
     description: For stock categories
@@ -41,6 +37,5 @@ properties:
     description: For unincorporated landlords, on profit and loss categories
     example: https://api.freeagent.com/v2/properties/1
   contact:
-    type: string
+    $ref: '#/components/schemas/ResourceID'
     description: Opening balances only, for Trade Debtors (681) and Trade Creditors (796) - a 422 on any other set
-    example: https://api.freeagent.com/v2/contacts/1

openapi/components/schemas/ProjectCreatePayload.yaml

@@ -7,8 +7,7 @@ required:
 - budget_units
 properties:
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/1
+    $ref: '#/components/schemas/ResourceID'
   name:
     type: string
     example: Website Development

openapi/components/schemas/ProjectUpdatePayload.yaml

@@ -2,8 +2,7 @@ type: object
 description: Fields left out are kept - an empty contract_po_reference, starts_on or ends_on removes it
 properties:
   contact:
-    type: string
-    example: https://api.freeagent.com/v2/contacts/1
+    $ref: '#/components/schemas/ResourceID'
   name:
     type: string
     example: Website Development

openapi/components/schemas/ResourceID.yaml

@@ -0,0 +1,3 @@
+type: string
+description: A record's URL or its ID
+example: '1'

openapi/components/schemas/TimeslipCreatePayload.yaml

@@ -5,15 +5,12 @@ required:
 - dated_on
 properties:
   user:
-    type: string
-    example: https://api.freeagent.com/v2/users/1
+    $ref: '#/components/schemas/ResourceID'
   project:
-    type: string
+    $ref: '#/components/schemas/ResourceID'
     description: Documented as required, but FreeAgent always uses the task's project and ignores this
-    example: https://api.freeagent.com/v2/projects/1
   task:
-    type: string
-    example: https://api.freeagent.com/v2/tasks/1
+    $ref: '#/components/schemas/ResourceID'
   dated_on:
     type: string
     example: '2026-10-02'

openapi/components/schemas/TimeslipUpdatePayload.yaml

@@ -1,11 +1,9 @@
 type: object
 properties:
   user:
-    type: string
-    example: https://api.freeagent.com/v2/users/1
+    $ref: '#/components/schemas/ResourceID'
   task:
-    type: string
-    example: https://api.freeagent.com/v2/tasks/1
+    $ref: '#/components/schemas/ResourceID'
   dated_on:
     type: string
     example: '2026-10-02'

openapi/openapi.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: FreeAgent
   version: '2026-09-01'
@@ -295,6 +295,8 @@ components:
       $ref: 'components/schemas/ProjectCreatePayload.yaml'
     ProjectUpdatePayload:
       $ref: 'components/schemas/ProjectUpdatePayload.yaml'
+    ResourceID:
+      $ref: 'components/schemas/ResourceID.yaml'
     Currency:
       $ref: 'components/schemas/Currency.yaml'
     ProjectStatus:
@@ -478,8 +480,10 @@ components:
       $ref: 'components/parameters/PeriodEndsOn.yaml'
     PaymentDate:
       $ref: 'components/parameters/PaymentDate.yaml'
-    UserId:
-      $ref: 'components/parameters/UserId.yaml'
+    ID:
+      $ref: 'components/parameters/ID.yaml'
+    UserID:
+      $ref: 'components/parameters/UserID.yaml'
   headers:
     Link:
       $ref: 'components/headers/Link.yaml'

openapi/paths/attachments.yaml

@@ -26,9 +26,4 @@ show:
       default:
         $ref: '#/components/responses/ErrorResponse'
   parameters:
-  - name: id
-    in: path
-    required: true
-    schema:
-      type: string
-      example: ''
+  - $ref: '#/components/parameters/ID'