@Schema and @SchemaProperty map the same attributes. Every attribute the two annotations share is applied by one mapping: bounds and their exclusive forms, multipleOf, lengths, pattern, item and property counts, requiredProperties, nullable, readOnly, writeOnly, deprecated, enumeration, defaultValue, constValue, examples, externalDocs (with its extensions), composition (allOf, anyOf, oneOf, not), the discriminator, and the JSON Schema 2020-12 keywords (if/then/else, contains, prefixItems, patternProperties, propertyNames, dependentSchemas, contentSchema, …). When a field’s @Schema and the class’s @Schema(properties = @SchemaProperty(…​)) both describe a property, the @SchemaProperty is applied last, attribute by attribute.

An attribute left at its default writes nothing. A schema no longer carries minItems: 2147483647, maxItems: -2147483648 or maxProperties: 0 because some other attribute was set; an explicit value, 0 included, is written.

A partial @Schema counts. On a parameter, a request body, a header or a content entry, a @Schema that sets any attribute (only minimum, only examples, only oneOf, …) is applied on top of the inferred schema. An empty @Schema() still gives the inferred schema.

constValue and examples are JSON unless the type is STRING. With type = STRING the value is the literal string; with any other type it is parsed as JSON, so @Schema(type = INTEGER, examples = "1") gives the number 1 and an object example is an object. A value that is not valid JSON stays the string as written. The deprecated example attribute is always copied as written.

@Extension(parseValue = true) uses a strict JSON reader — the reader of static files. null, 1e3, escaped quotes and nested arrays come out as JSON says. Lenient forms that are not JSON ({a: 1}, single quotes, TRUE, 1L) stay strings, and a JSON null adds no extension.

@Digits gives multipleOf or pattern (MicroProfile OpenAPI 4.2), when mp.openapi.scan.beanvalidation is not false: multipleOf of 10^-fraction on a number schema, a pattern such as ^-?\d{1,5}(\.\d{1,2})?$ on a string schema, nothing on an integer schema. A value set explicitly on the schema is never overridden. Decimal values are written as plain decimals in JSON and YAML (0.0000000001, not 1E-10), so a YAML 1.1 parser still reads them as numbers.

A @DiscriminatorMapping or @PatternProperty with no schema (left at Void.class) is skipped instead of producing an empty entry.

Standard keywords get their model type. minimum, maxLength, not, discriminator, xml, externalDocs, allOf, … become typed Schema properties, nested schemas included, and true/false subschemas become boolean schemas. They are no longer stored as extensions, so an OASFilter that clears a schema’s extensions keeps them. A value of another JSON type is kept as written, for an alternative dialect.

Unknown keywords are extensions (MicroProfile OpenAPI 4.2). A Schema keeps any property it does not know, x- or not, and writes it back. Schema.getAll() lists every property set, standard ones and $ref included, under its JSON name, and Schema.setAll(…​) clears them all before setting the new ones, as the 4.2 Javadoc says.

$ref is kept as written on schemas and on the referenceable objects — parameters, request bodies and responses (whose $ref used to be dropped), callbacks (whose $ref used to be read as a callback expression), path items: a document reference such as Pet.yaml is not expanded into #/components/…​, in the static file and when models merge.

Every field is read. A parameter keeps style, explode, allowReserved, deprecated, allowEmptyValue, example, examples and content; a header keeps style, explode, content, example and examples; a discriminator keeps its x- keys. type: "null" (alone or in a type array) is SchemaType.NULL, and a type name that is not a JSON Schema type is kept as written.

YAML numbers follow YAML 1.2: +1, 1e3, .5, 0o17 and 0x1F are numbers; integers beyond a long are read as BigInteger.

In mp.openapi.schema.<FQCN>, the historical ref key is accepted at every level of the schema, $defs and definitions included, and expands a short name to #/components/schemas/<name>. An explicit $ref is kept as written, as in a static file.

vauban-api is a runtime dependency of grimm-cdi-vauban, under any container. The Vauban build weaves a protected constructor taking io.vidocq.vauban.api.ProxyLink into each normal-scoped bean (GrimmModelCache, OpenApiResource, GrimmAutoDiscovery); a container that cannot load that type cannot load the class, and Weld drops the bean with an INFO message (WELD-000119). vauban-api holds API types only (13 KB): no Vauban code runs outside Vauban. Its Jakarta CDI dependencies are excluded.

Each container has its own document — see Internals.

A complete document in annotated mode — compile the application with grimm-processor: the resources it describes enter the document even when they are not CDI beans.

grimm-processor carries Jakarta REST — it reads the Jakarta REST annotations, and an annotationProcessorPaths entry only resolves its compile and runtime dependencies; the API used to be provided there, so the processor could not load from such an entry.

Java 25 (LTS), Maven 3.9.16.

JAX-RS 4.0 (Cassini or any conformant runtime).

CDI 4.1 Lite (Vauban) or Lite-compatible — proven on Weld SE 6.0 and Open Liberty (CDI 4.0): see Other CDI containers NEW.

No Jakarta EE Full Profile dependency.

BUG.md — tracked reproducible bugs (to be created if missing).

BENCH.md — JMH benchmarks (to be created if missing).

Concepts — merge, filters, configuration.

Internals — pipeline and threading.

TCK — status and execution.