Description

Machine-readable API description for Mesh services

Overview

Mesh Description provides a standardized interface description format for Mesh APIs. It enables both humans and machines to discover service capabilities without accessing source code or documentation.

Services supporting description MUST implement mesh.describe.

Specification Version

Current Version: 0.1

Version follows Semantic Versioning. Tools supporting version 0.1.0 should work with all 0.1.x documents.

Document Structure

Description Document Object

The root object describing a Mesh service.

Field	Type	Required	Description
`mesh`	string	YES	Mesh protocol version (e.g., `"0.1.0"`)
`describe`	string	YES	Description spec version (e.g., `"0.1.0"`)
`info`	Info Object	YES	Service metadata
`servers`	[Server Object]	NO	Connectivity information
`functions`	[Function Object]	YES	Available functions
`resources`	Map[string, Resource Object]	NO	Resource type definitions
`components`	Components Object	NO	Reusable definitions
`external_docs`	External Documentation Object	NO	Additional documentation

Example

{
  "mesh": "0.1.0",
  "describe": "0.1.0",
  "info": {
    "title": "Orders API",
    "version": "2.3.0",
    "description": "Order management service"
  },
  "functions": [
    {
      "name": "orders.get",
      "version": "2",
      "summary": "Retrieve an order by ID",
      "arguments": [...],
      "result": {...}
    }
  ]
}

Info Object

Provides service metadata.

Field	Type	Required	Description
`title`	string	YES	Service title
`version`	string	YES	Service version (not protocol version)
`description`	string	NO	Service description (Markdown supported)
`terms_of_service`	string	NO	URL to terms of service
`contact`	Contact Object	NO	Contact information
`license`	License Object	NO	License information

Contact Object

Field	Type	Required
`name`	string	NO
`url`	string	NO
`email`	string	NO

License Object

Field	Type	Required
`name`	string	YES
`url`	string	NO

Example

{
  "info": {
    "title": "Orders API",
    "version": "2.3.0",
    "description": "Manages customer orders and fulfillment",
    "contact": {
      "name": "Platform Team",
      "email": "platform@example.com"
    },
    "license": {
      "name": "Proprietary"
    }
  }
}

Server Object

Represents a server endpoint.

Field	Type	Required	Description
`name`	string	YES	Server name
`url`	string	YES	Server URL (supports variables)
`description`	string	NO	Server description
`variables`	Map[string, Server Variable]	NO	URL template variables

Server Variable Object

Field	Type	Required	Description
`enum`	[string]	NO	Allowed values
`default`	string	YES	Default value
`description`	string	NO	Variable description

Example

{
  "servers": [
    {
      "name": "production",
      "url": "https://orders-api.internal",
      "description": "Production cluster"
    },
    {
      "name": "staging",
      "url": "https://orders-api.staging.internal",
      "description": "Staging environment"
    }
  ]
}

Function Object

Describes a callable function. Each function name + version combination MUST be unique.

Field	Type	Required	Description
`name`	string	YES	Function name (e.g., `orders.create`)
`version`	string	YES	Function version
`summary`	string	NO	Brief description
`description`	string	NO	Detailed description (Markdown supported)
`tags`	[Tag Object \| Reference]	NO	Logical grouping
`arguments`	[Argument Object]	YES	Function parameters
`result`	Result Object	NO	Return value schema
`errors`	[Error Definition]	NO	Possible errors
`query`	Query Capabilities Object	NO	Query features for list functions
`deprecated`	Deprecated Object	NO	Deprecation info (presence indicates deprecated)
`idempotent`	boolean	NO	Whether idempotent (default: `false`)
`discoverable`	boolean	NO	Whether included in description (default: `true`)
`examples`	[Example Object]	NO	Usage examples
`external_docs`	External Documentation Object	NO	Additional documentation

Example

{
  "name": "orders.create",
  "version": "2",
  "summary": "Create a new order",
  "description": "Creates an order for a customer with the specified items.",
  "tags": [{ "name": "orders" }],
  "arguments": [
    {
      "name": "customer_id",
      "schema": { "type": "string" },
      "required": true,
      "description": "Customer identifier"
    },
    {
      "name": "items",
      "schema": {
        "type": "array",
        "items": { "$ref": "#/components/schemas/OrderItem" }
      },
      "required": true,
      "description": "Order line items"
    }
  ],
  "result": {
    "resource": "order",
    "description": "The created order"
  },
  "errors": [
    { "$ref": "#/components/errors/CustomerNotFound" },
    { "$ref": "#/components/errors/InsufficientInventory" }
  ],
  "idempotent": false
}

Non-Discoverable Functions

Functions marked discoverable: false MUST NOT appear in mesh.describe responses. This allows debug, admin, or infrastructure functions to exist without being advertised.

Non-discoverable functions remain callable—they simply aren’t listed in description.

Argument Object

Describes a function parameter.

Field	Type	Required	Description
`name`	string	YES	Parameter name
`schema`	Schema Object	YES	JSON Schema for the parameter
`required`	boolean	NO	Whether required (default: `false`)
`summary`	string	NO	Brief description
`description`	string	NO	Detailed description
`default`	any	NO	Default value if not provided
`deprecated`	Deprecated Object	NO	Deprecation info (presence indicates deprecated)
`examples`	[any]	NO	Example values

Ordering Rule: Required parameters SHOULD precede optional parameters.

Example

{
  "name": "customer_id",
  "schema": {
    "type": "string",
    "pattern": "^cust_[a-zA-Z0-9]+$"
  },
  "required": true,
  "description": "Unique customer identifier",
  "examples": ["cust_abc123"]
}

Result Object

Describes the function return value.

Field	Type	Required	Description
`resource`	string	NO	Resource type name (for resource responses)
`schema`	Schema Object	NO	JSON Schema (for non-resource responses)
`collection`	boolean	NO	Whether returns array of resources (default: `false`)
`description`	string	NO	Result description

One of resource or schema SHOULD be provided.

Examples

Single Resource:

{
  "result": {
    "resource": "order",
    "description": "The requested order"
  }
}

Resource Collection:

{
  "result": {
    "resource": "order",
    "collection": true,
    "description": "List of matching orders"
  }
}

Non-Resource:

{
  "result": {
    "schema": {
      "type": "object",
      "properties": {
        "valid": { "type": "boolean" },
        "errors": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "description": "Validation result"
  }
}

Resource Object

Defines a resource type and its queryable capabilities.

Field	Type	Required	Description
`type`	string	YES	Resource type identifier
`description`	string	NO	Resource description
`attributes`	Map[string, Attribute Object]	YES	Resource attributes
`relationships`	Map[string, Relationship Definition]	NO	Available relationships
`meta`	[Schema Object]	NO	Schema for resource-level metadata

Example

{
  "resources": {
    "order": {
      "type": "order",
      "description": "A customer order",
      "attributes": {
        "id": {
          "schema": { "type": "string" },
          "description": "Unique identifier",
          "filterable": true,
          "sortable": false
        },
        "order_number": {
          "schema": { "type": "string" },
          "description": "Human-readable order number",
          "filterable": true,
          "sortable": true
        },
        "status": {
          "schema": {
            "type": "string",
            "enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
          },
          "description": "Order status",
          "filterable": true,
          "filter_operators": ["equals", "not_equals", "in"],
          "sortable": true
        },
        "total_amount": {
          "schema": { "$ref": "#/components/schemas/Money" },
          "description": "Order total",
          "filterable": true,
          "filter_operators": ["equals", "greater_than", "less_than", "between"],
          "sortable": true
        },
        "created_at": {
          "schema": { "type": "string", "format": "date-time" },
          "description": "Creation timestamp",
          "filterable": true,
          "filter_operators": ["equals", "greater_than", "less_than", "between"],
          "sortable": true
        }
      },
      "relationships": {
        "customer": {
          "resource": "customer",
          "cardinality": "one",
          "description": "The ordering customer",
          "filterable": true
        },
        "items": {
          "resource": "order_item",
          "cardinality": "many",
          "description": "Order line items"
        }
      }
    }
  }
}

Attribute Object

Defines a resource attribute.

Field	Type	Required	Description
`schema`	Schema Object	YES	JSON Schema for the attribute
`description`	string	NO	Attribute description
`filterable`	boolean	NO	Can be used in filters (default: `false`)
`filter_operators`	[string]	NO	Allowed filter operators
`sortable`	boolean	NO	Can be used in sorts (default: `false`)
`sparse`	boolean	NO	Can be sparse-selected (default: `true`)
`deprecated`	Deprecated Object	NO	Deprecation info (presence indicates deprecated)

Filter Operators

When filterable is true, specify allowed operators:

Operator	Description
`equals`	Exact match
`not_equals`	Not equal
`greater_than`	Greater than
`greater_than_or_equal_to`	Greater than or equal
`less_than`	Less than
`less_than_or_equal_to`	Less than or equal
`like`	Pattern match (SQL LIKE)
`not_like`	Negated pattern match
`in`	Value in array
`not_in`	Value not in array
`between`	Value between two bounds
`is_null`	Is null check
`is_not_null`	Is not null check

If filter_operators is omitted, defaults to ["equals"].

Relationship Definition Object

Defines a relationship to another resource.

Field	Type	Required	Description
`resource`	string	YES	Related resource type
`cardinality`	string	YES	`"one"` or `"many"`
`description`	string	NO	Relationship description
`filterable`	boolean	NO	Can filter by related attributes
`includable`	boolean	NO	Can be included (default: `true`)
`nested`	[string]	NO	Nested relationships allowed (e.g., `["product"]`)

Query Capabilities Object

Describes query features for list/search functions.

Field	Type	Required	Description
`filters`	Filters Capability	NO	Filter support
`sorts`	Sorts Capability	NO	Sort support
`fields`	Fields Capability	NO	Sparse fieldset support
`relationships`	Relationships Capability	NO	Relationship inclusion
`pagination`	Pagination Capability	NO	Pagination support

Filters Capability

Field	Type	Required	Description
`enabled`	boolean	YES	Whether filtering is supported
`boolean_logic`	boolean	NO	Supports `and`/`or` combinators
`resources`	[string]	NO	Filterable resource types (default: `["self"]`)

Sorts Capability

Field	Type	Required	Description
`enabled`	boolean	YES	Whether sorting is supported
`max_sorts`	integer	NO	Maximum simultaneous sort fields
`default_sort`	Sort Default	NO	Default sort if none specified

Sort Default

{
  "attribute": "created_at",
  "direction": "desc"
}

Fields Capability

Field	Type	Required	Description
`enabled`	boolean	YES	Whether sparse fieldsets supported
`default_fields`	Map[string, [string]]	NO	Default fields per resource type

Relationships Capability

Field	Type	Required	Description
`enabled`	boolean	YES	Whether relationship inclusion supported
`available`	[string]	NO	Available relationships
`max_depth`	integer	NO	Maximum nesting depth

Pagination Capability

Field	Type	Required	Description
`styles`	[string]	YES	Supported styles: `"offset"`, `"cursor"`, `"keyset"`
`default_style`	string	NO	Default pagination style
`default_limit`	integer	NO	Default page size
`max_limit`	integer	NO	Maximum page size

Example

{
  "query": {
    "filters": {
      "enabled": true,
      "boolean_logic": true,
      "resources": ["self", "customer"]
    },
    "sorts": {
      "enabled": true,
      "max_sorts": 3,
      "default_sort": {
        "attribute": "created_at",
        "direction": "desc"
      }
    },
    "fields": {
      "enabled": true,
      "default_fields": {
        "self": ["id", "order_number", "status", "total_amount", "created_at"]
      }
    },
    "relationships": {
      "enabled": true,
      "available": ["customer", "items", "shipping_address"],
      "max_depth": 2
    },
    "pagination": {
      "styles": ["cursor", "offset"],
      "default_style": "cursor",
      "default_limit": 25,
      "max_limit": 100
    }
  }
}

Error Definition Object

Defines a possible error response.

Field	Type	Required	Description
`code`	string	YES	Error code
`message`	string	YES	Human-readable message
`description`	string	NO	When this error occurs
`retryable`	boolean	NO	Whether retryable
`details`	Schema Object	NO	Schema for error details field

Example

{
  "code": "CUSTOMER_NOT_FOUND",
  "message": "Customer not found",
  "description": "Returned when the specified customer_id does not exist",
  "retryable": false
}

Example Object

Provides a complete request/response example.

Field	Type	Required	Description
`name`	string	YES	Example name
`summary`	string	NO	Brief description
`description`	string	NO	Detailed explanation
`arguments`	object	YES	Example parameter values
`result`	any	NO	Expected result (omit for error examples)
`error`	object	NO	Expected error (for error examples)

Example

{
  "examples": [
    {
      "name": "Create simple order",
      "summary": "Creates an order with a single item",
      "arguments": {
        "customer_id": "cust_abc123",
        "items": [
          { "sku": "WIDGET-01", "quantity": 2 }
        ]
      },
      "result": {
        "data": {
          "type": "order",
          "id": "ord_xyz789",
          "attributes": {
            "order_number": "ORD-2024-0001",
            "status": "pending",
            "total_amount": { "amount": "59.98", "currency": "USD" }
          }
        }
      }
    },
    {
      "name": "Invalid customer",
      "summary": "Error when customer doesn't exist",
      "arguments": {
        "customer_id": "cust_invalid",
        "items": [
          { "sku": "WIDGET-01", "quantity": 1 }
        ]
      },
      "errors": [{
        "code": "CUSTOMER_NOT_FOUND",
        "message": "Customer not found",
        "retryable": false,
        "source": {
          "pointer": "/call/arguments/customer_id"
        }
      }]
    }
  ]
}

Tag Object

Logical grouping for functions.

Field	Type	Required	Description
`name`	string	YES	Tag name
`summary`	string	NO	Brief description
`description`	string	NO	Detailed description
`external_docs`	External Documentation Object	NO	Additional documentation

Deprecated Object

Indicates a function is deprecated. Presence of this object means the function is deprecated.

Field	Type	Required	Description
`reason`	string	NO	Why deprecated and what to use instead
`sunset`	string	NO	ISO 8601 date when function will be removed

Example

{
  "deprecated": {
    "reason": "Use version 2 which supports bulk operations",
    "sunset": "2025-06-01"
  }
}

External Documentation Object

Reference to external documentation.

Field	Type	Required	Description
`url`	string	YES	Documentation URL
`description`	string	NO	Description

Components Object

Holds reusable definitions.

Field	Type	Description
`schemas`	Map[string, Schema Object]	Reusable JSON Schemas
`arguments`	Map[string, Argument Object]	Reusable parameters
`errors`	Map[string, Error Definition]	Reusable error definitions
`examples`	Map[string, Example Object]	Reusable examples
`tags`	Map[string, Tag Object]	Reusable tags
`resources`	Map[string, Resource Object]	Reusable resource definitions

Component keys MUST match pattern: ^[a-zA-Z0-9._-]+$

Objects in components have no effect unless referenced.

Example

{
  "components": {
    "schemas": {
      "Money": {
        "type": "object",
        "properties": {
          "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
        },
        "required": ["amount", "currency"]
      },
      "OrderItem": {
        "type": "object",
        "properties": {
          "sku": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 }
        },
        "required": ["sku", "quantity"]
      }
    },
    "errors": {
      "CUSTOMER_NOT_FOUND": {
        "code": "CUSTOMER_NOT_FOUND",
        "message": "Customer not found",
        "retryable": false
      },
      "INSUFFICIENT_INVENTORY": {
        "code": "INSUFFICIENT_INVENTORY",
        "message": "Insufficient inventory",
        "retryable": true,
        "details": {
          "type": "object",
          "properties": {
            "sku": { "type": "string" },
            "requested": { "type": "integer" },
            "available": { "type": "integer" }
          }
        }
      }
    }
  }
}

Reference Object

Enables reuse via JSON Reference.

Field	Type	Required
`$ref`	string	YES

Reference paths follow JSON Pointer syntax:

#/components/schemas/Money — Local reference
common.json#/components/schemas/Money — External reference

Example

{
  "arguments": [
    {
      "name": "amount",
      "schema": { "$ref": "#/components/schemas/Money" },
      "required": true
    }
  ]
}

Schema Object

Follows JSON Schema Draft-07.

Common patterns:

// String with pattern
{
  "type": "string",
  "pattern": "^[a-z0-9_]+$",
  "minLength": 1,
  "maxLength": 64
}

// Enum
{
  "type": "string",
  "enum": ["pending", "processing", "shipped"]
}

// Array
{
  "type": "array",
  "items": { "$ref": "#/components/schemas/OrderItem" },
  "minItems": 1
}

// Object
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Description Function

Services MUST implement mesh.describe to return the Description Document.

mesh.describe

Returns the complete description document or describes a specific function.

Parameters:

Name	Type	Required	Description
`function`	string	NO	Specific function to describe
`version`	string	NO	Specific version (with `function`)

Result: Description Document Object (or subset for specific function)

Functions with discoverable: false are always excluded from the response.

Full Description

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_describe",
  "call": {
    "function": "mesh.describe",
    "version": "1",
    "arguments": {}
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_describe",
  "result": {
    "mesh": "0.1.0",
    "describe": "0.1.0",
    "info": {
      "title": "Orders API",
      "version": "2.3.0"
    },
    "functions": [
      { "name": "orders.get", "version": "2", ... },
      { "name": "orders.list", "version": "2", ... },
      { "name": "orders.create", "version": "2", ... }
    ],
    "resources": {
      "order": { ... },
      "order_item": { ... }
    },
    "components": { ... }
  }
}

Single Function

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_describe_fn",
  "call": {
    "function": "mesh.describe",
    "version": "1",
    "arguments": {
      "function": "orders.list",
      "version": "2"
    }
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_describe_fn",
  "result": {
    "name": "orders.list",
    "version": "2",
    "summary": "List orders",
    "arguments": [...],
    "result": {
      "resource": "order",
      "collection": true
    },
    "query": {
      "filters": { "enabled": true, ... },
      "sorts": { "enabled": true, ... },
      "pagination": { "styles": ["cursor"], ... }
    }
  }
}

Specification Extensions

Custom extensions use fields prefixed with x-:

{
  "name": "orders.create",
  "version": "2",
  "x-rate-limit": {
    "requests": 100,
    "window": { "value": 1, "unit": "minute" }
  },
  "x-owner": "orders-team"
}

Extensions MAY appear in any object. Tooling MAY ignore unknown extensions.

Complete Example

{
  "mesh": "0.1.0",
  "describe": "0.1.0",
  "info": {
    "title": "Orders API",
    "version": "2.3.0",
    "description": "Order management service for the e-commerce platform",
    "contact": {
      "name": "Platform Team",
      "email": "platform@example.com"
    }
  },
  "servers": [
    {
      "name": "production",
      "url": "https://orders-api.internal"
    }
  ],
  "functions": [
    {
      "name": "orders.get",
      "version": "2",
      "summary": "Get an order by ID",
      "tags": [{ "name": "orders" }],
      "arguments": [
        {
          "name": "id",
          "schema": { "type": "string" },
          "required": true,
          "description": "Order ID"
        }
      ],
      "result": {
        "resource": "order",
        "description": "The requested order"
      },
      "query": {
        "fields": {
          "enabled": true
        },
        "relationships": {
          "enabled": true,
          "available": ["customer", "items", "shipping_address"],
          "max_depth": 2
        }
      },
      "errors": [
        { "$ref": "#/components/errors/NotFound" }
      ],
      "examples": [
        {
          "name": "Get order",
          "arguments": { "id": "ord_xyz789" },
          "result": {
            "details": {
              "type": "order",
              "id": "ord_xyz789",
              "attributes": {
                "order_number": "ORD-2024-0001",
                "status": "pending",
                "total_amount": { "amount": "99.99", "currency": "USD" },
                "created_at": "2024-01-15T10:30:00Z"
              }
            }
          }
        }
      ]
    },
    {
      "name": "orders.list",
      "version": "2",
      "summary": "List orders",
      "tags": [{ "name": "orders" }],
      "arguments": [],
      "result": {
        "resource": "order",
        "collection": true,
        "description": "Paginated list of orders"
      },
      "query": {
        "filters": {
          "enabled": true,
          "boolean_logic": true,
          "resources": ["self", "customer"]
        },
        "sorts": {
          "enabled": true,
          "max_sorts": 2,
          "default_sort": { "attribute": "created_at", "direction": "desc" }
        },
        "fields": {
          "enabled": true,
          "default_fields": {
            "self": ["id", "order_number", "status", "total_amount", "created_at"]
          }
        },
        "relationships": {
          "enabled": true,
          "available": ["customer", "items"],
          "max_depth": 2
        },
        "pagination": {
          "styles": ["cursor", "offset"],
          "default_style": "cursor",
          "default_limit": 25,
          "max_limit": 100
        }
      }
    },
    {
      "name": "orders.create",
      "version": "2",
      "summary": "Create a new order",
      "tags": [{ "name": "orders" }],
      "arguments": [
        {
          "name": "customer_id",
          "schema": { "type": "string" },
          "required": true
        },
        {
          "name": "items",
          "schema": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/OrderItemInput" },
            "minItems": 1
          },
          "required": true
        },
        {
          "name": "shipping_address_id",
          "schema": { "type": "string" },
          "required": false
        }
      ],
      "result": {
        "resource": "order",
        "description": "The created order"
      },
      "idempotent": false,
      "errors": [
        { "$ref": "#/components/errors/NotFound" },
        { "$ref": "#/components/errors/InvalidArguments" },
        { "$ref": "#/components/errors/InsufficientInventory" }
      ]
    }
  ],
  "resources": {
    "order": {
      "type": "order",
      "description": "A customer order",
      "attributes": {
        "id": {
          "schema": { "type": "string" },
          "filterable": true,
          "sortable": false,
          "sparse": true
        },
        "order_number": {
          "schema": { "type": "string" },
          "filterable": true,
          "filter_operators": ["equals", "like"],
          "sortable": true
        },
        "status": {
          "schema": {
            "type": "string",
            "enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
          },
          "filterable": true,
          "filter_operators": ["equals", "not_equals", "in"],
          "sortable": true
        },
        "total_amount": {
          "schema": { "$ref": "#/components/schemas/Money" },
          "filterable": true,
          "filter_operators": ["equals", "greater_than", "less_than", "between"],
          "sortable": true
        },
        "item_count": {
          "schema": { "type": "integer" },
          "filterable": false,
          "sortable": true
        },
        "created_at": {
          "schema": { "type": "string", "format": "date-time" },
          "filterable": true,
          "filter_operators": ["equals", "greater_than", "less_than", "between"],
          "sortable": true
        },
        "updated_at": {
          "schema": { "type": "string", "format": "date-time" },
          "filterable": true,
          "filter_operators": ["greater_than", "less_than"],
          "sortable": true
        }
      },
      "relationships": {
        "customer": {
          "resource": "customer",
          "cardinality": "one",
          "filterable": true,
          "includable": true
        },
        "items": {
          "resource": "order_item",
          "cardinality": "many",
          "filterable": false,
          "includable": true,
          "nested": ["product"]
        },
        "shipping_address": {
          "resource": "address",
          "cardinality": "one",
          "filterable": false,
          "includable": true
        }
      }
    },
    "customer": {
      "type": "customer",
      "attributes": {
        "id": { "schema": { "type": "string" }, "filterable": true },
        "name": { "schema": { "type": "string" }, "filterable": true, "filter_operators": ["equals", "like"] },
        "email": { "schema": { "type": "string", "format": "email" }, "filterable": true },
        "type": {
          "schema": { "type": "string", "enum": ["standard", "premium", "vip"] },
          "filterable": true,
          "filter_operators": ["equals", "in"]
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Money": {
        "type": "object",
        "properties": {
          "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
        },
        "required": ["amount", "currency"]
      },
      "OrderItemInput": {
        "type": "object",
        "properties": {
          "sku": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 }
        },
        "required": ["sku", "quantity"]
      }
    },
    "errors": {
      "NOT_FOUND": {
        "code": "NOT_FOUND",
        "message": "Resource not found",
        "retryable": false
      },
      "INVALID_ARGUMENTS": {
        "code": "INVALID_ARGUMENTS",
        "message": "Invalid arguments provided",
        "retryable": false
      },
      "INSUFFICIENT_INVENTORY": {
        "code": "INSUFFICIENT_INVENTORY",
        "message": "Insufficient inventory",
        "retryable": true,
        "details": {
          "type": "object",
          "properties": {
            "sku": { "type": "string" },
            "requested": { "type": "integer" },
            "available": { "type": "integer" }
          }
        }
      }
    }
  }
}

Formatting Standards

Aspect	Standard
Format	JSON (RFC 7159)
File name	`mesh.json` or `mesh-describe.json`
Case sensitivity	All field names are case-sensitive
Naming	`snake_case` for field names
Rich text	GitHub Flavored Markdown
Versioning	Semantic Versioning