For AI agents: llms.txt is a short guide that sends you to the rules your problem needs, and rules.json holds every rule of this playbook as JSON.

How to do it

One schema then serves reads and writes, and docs, generated clients and agents see which fields they may send. JSON Schema lets a server either ignore a read-only field in a request or reject it with 422. Pick one and document it. Ignoring suits PUT, where clients send back what they read. Never copy a read-only field into the record, as Accept only the fields you expect says. Never return a write-only field in any response.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

YAML example

Customer:
  type: object
  properties:
    id: { type: string, readOnly: true }
    createdAt: { type: string, format: date-time, readOnly: true }
    email: { type: string, format: email }
    password: { type: string, writeOnly: true }

JavaScript example

import { z } from 'zod'

const Customer = z.object({ id: z.string(), createdAt: z.iso.datetime(), email: z.email() })
const CustomerInput = z.strictObject({ email: z.email(), password: z.string() })

Python example

from datetime import datetime
from pydantic import BaseModel, ConfigDict, EmailStr

class CustomerInput(BaseModel):
    model_config = ConfigDict(extra="forbid")
    email: EmailStr
    password: str

class Customer(BaseModel):
    id: str
    created_at: datetime
    email: EmailStr

How to check

A linter rule finds readOnly: true on every id, createdAt and updatedAt, and writeOnly: true on every field named password or secret. A contract test sends an update with a changed id and createdAt, and the stored values stay the same. No response in the contract tests holds a write-only field.

Sources

• OpenAPI 3.2.1 Validating readOnly and writeOnly
• JSON Schema 2020-12 Validation

Related rules

• Accept only the fields you expect in Security testing