docs: document conditional requirement labels on API fields

agent-context/context/skills/mintlify/reference/api-docs.md

@@ -109,6 +109,13 @@ For OpenAPI 3.1 and 3.2 specs, describe a file upload field as a string schema w
 - `contentEncoding` of `base64` or `base64url` sends the file as base64; other values use binary handling. A `contentEncoding` without a binary `contentMediaType` stays a text field.
 - The legacy `format: "binary"` and `format: "base64"` fields remain supported.
 
+### Conditional requirements
+
+OpenAPI 3.1 schemas can require a property only in some cases with `if`/`then`/`else`, `dependentRequired`, and `dependentSchemas`. Endpoint pages label each affected field with a "required" pill followed by its condition, for example "required if `method` = `card`", "required unless `method` = `card`" (from `else`), or "required if `tax_id` is set" (from `dependentRequired`).
+
+- Conditions are summarized when `if` tests sibling properties with `const`, `enum`, `type`, or presence (`required`). Anything more complex shows a generic "conditionally required" pill.
+- A property test in `if` also passes when the property is missing, so the tested property must be required (in the object's `required` or the `if` schema's `required`) to get a specific label. Otherwise the field shows "conditionally required".
+
 ## OpenAPI extensions
 
 - `x-hidden`: Creates page but hides from navigation.

api-playground/complex-data-types.mdx

@@ -98,3 +98,53 @@ delivery_address:
     </Tabs>
   </div>
 </ParamField>
+
+## Conditional requirements
+
+In OpenAPI 3.1, you can make a property required only in certain cases with the `if`, `then`, `else`, `dependentRequired`, and `dependentSchemas` keywords. Mintlify reads these keywords and labels each affected field on the endpoint page with a **required** pill followed by its condition.
+
+For example, this schema requires a card number for card payments, an account number for every other payment method, and a company name whenever the request includes a tax ID:
+
+```yaml
+Payment:
+  type: object
+  required:
+    - method
+  properties:
+    method:
+      type: string
+      enum: [card, bank_transfer]
+    card_number:
+      type: string
+    account_number:
+      type: string
+    tax_id:
+      type: string
+    company_name:
+      type: string
+  if:
+    properties:
+      method:
+        const: card
+  then:
+    required:
+      - card_number
+  else:
+    required:
+      - account_number
+  dependentRequired:
+    tax_id:
+      - company_name
+```
+
+The endpoint page labels these fields:
+
+- `card_number`: required if `method` = `card`
+- `account_number`: required unless `method` = `card`
+- `company_name`: required if `tax_id` is set
+
+Mintlify summarizes conditions that test sibling properties for specific values with `const` or `enum`, or for presence with `required`. When a condition is too complex to summarize, the field shows a **conditionally required** pill instead.
+
+<Tip>
+  A property test in `if` also passes when the property is missing. To get a specific label, make the tested property required, either in the object's `required` list or in the `if` schema's `required` list. Otherwise, the field shows the **conditionally required** pill.
+</Tip>

mint-instructions/api-docs/sdk.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Advanced API and SDK reference"
 name: mintlify-api-docs-sdk
 description: "Covers SDK reference pages from doc-tool output, x-codeSamples, oneOf/anyOf/allOf, multiple responses, endpoint visibility, and manual MDX API pages."
 when: "SDK reference pages, x-codeSamples, oneOf/anyOf, multiple responses, hiding endpoints"
 related: false
@@ -10,8 +10,8 @@
 ## Workflow
 
 1. SDK reference from a doc tool: generate a machine-readable artifact, then add `sdk` to a tab or group in `docs.json` (see Examples).
    - TypeDoc: `npx typedoc --json typedoc.json src/index.ts` (JSON file, `format: "typedoc"`)
    - DocFX: `docfx metadata docfx.json` (output directory, `format: "docfx"`)
    - Javadoc: `javadoc -d javadoc-output -sourcepath src/main/java -subpackages com.example` (standard doclet HTML directory, `format: "javadoc"`)
    - Sphinx: `python -m sphinx -b json docs/source artifacts/json` (JSON builder directory, `format: "sphinx"`)
    - phpDocumentor: `phpdoc -d src -t artifacts --template=xml` (`structure.xml`, `format: "phpdoc"`)
@@ -26,34 +26,35 @@
 ## Rules
 
 SDK reference (`sdk`):
 - Keys: `format` (required: `typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc`), `source` (required: relative path or HTTPS URL, HTTP is rejected), `directory` (URL prefix, default `sdk-reference`).
 - A tab with `sdk` may contain only `groups`: no `pages`, `versions`, `languages`, `openapi`, `asyncapi`, or `graphql`. A group with `sdk` may contain `pages` and nested groups, but not `graphql`.
 - Children inherit the parent `sdk`; a nested group with its own `sdk` overrides it.
 - Mintlify creates a page per class, interface, module, and function. Generated groups come after the tab's `groups` or the group's own `pages`. Ungrouped pages land in a `Reference` group.
 - TypeDoc pages group by `@category` and `@group` tags, else by symbol type.
 - Multiple libraries: one tab or group each, with unique `directory` values.
 - Remote `source`: `typedoc`/`phpdoc` take a file URL; `docfx`/`javadoc`/`sphinx` take a zip (Maven Central javadoc jars work). Limits: 50 MB download, 200 MB extracted. Remote changes need a new deployment (Trigger deployment API).
 - Per-symbol page: frontmatter `sdk: "class Client"` (pattern `[source] kind name`; methods/properties use `method Client.getUser`). Body renders first, generated reference is appended. The page must be in navigation.
 - Once any page in an `sdk` tab or group has `sdk` frontmatter, auto-population stops for that tab or group and only your pages show.
 - The string form inherits `format`, so it only works under an `sdk` tab or group. Elsewhere use the object form: `kind` (`class`, `interface`, `enum`, `function`, `type`, `variable`, `method`, `property`), `name`, `parent` (required for `method`/`property`), `format`, `source`.
 
 OpenAPI extensions and schemas:
 - `x-codeSamples` items: `lang` (required), `source` (required), `label` (optional, use it to tell several samples apart).
 - Speakeasy users: point `openapi` at the registry's `*-with-code-samples` combined spec URL, not the source spec.
 - `oneOf` and `anyOf` render the same: tabs named by each subschema's `title`. `not` is unsupported.
 - `allOf` of object schemas is merged into one object with all properties.
+- `if`/`then`/`else`, `dependentRequired` and `dependentSchemas` (OpenAPI 3.1) add a required pill plus its condition (`required if` or `required unless`) to affected fields. Mark properties tested in `if` as required, or the field gets a generic `conditionally required` pill.
 - Fields typed `any` or `undefined` render like `oneOf`, with a picker.
 - `audio/*` response content with a URL example renders an audio player.
 - `x-hidden`: page exists at its URL but is not in navigation. `x-excluded`: no page at all.
 
 Manual MDX pages:
 - `api` frontmatter is `METHOD` plus a full URL (ignores `api.mdx.server`) or a relative path (needs `api.mdx.server`). Path params use `{}`.
 - Page overrides: `playground: interactive | simple | none`, `authMethod: bearer | basic | key | none`.
 - `<ParamField>`: one of `query`, `path`, `body`, `header` set to the name, plus `type` (`number`, `string`, `boolean`, `object`, arrays with `[]` like `string[]`), `required`, `deprecated`, `default`, `placeholder`, `pre`, `post`. Adding one adds a playground.
 - `<ResponseField>`: `name` and `type` (required, any string), `default`, `required`, `deprecated`, `pre`, `post`.
 - Nest child fields in `<Expandable title="..." defaultOpen>`.
 - `<RequestExample>` / `<ResponseExample>` pin code blocks to the right sidebar; each block needs a title. `dropdown` prop: language dropdown instead of tabs.
 - Each manual page must be listed in `navigation` by file path.
 
 ## Examples
 
@@ -62,10 +63,10 @@
 ```json
 {
   "group": "TypeScript SDK",
   "sdk": {
     "format": "typedoc",
     "source": "sdk-artifacts/typedoc.json",
     "directory": "sdk/typescript"
   },
   "pages": ["sdk/typescript/overview"]
 }
@@ -168,7 +169,7 @@
 ## More
 
 - `mint instructions api-docs`: OpenAPI setup, playground settings, common errors.
 - https://www.mintlify.com/docs/api-playground/sdk-reference-setup
 - https://www.mintlify.com/docs/api-playground/adding-sdk-examples
 - https://www.mintlify.com/docs/api-playground/complex-data-types
 - https://www.mintlify.com/docs/api-playground/mdx-setup