Skip to content

JSON schema: move the element id mapping to docs.yaml and drop the legacy "id" keyword #3603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christiangoerdes merged 1 commit into from
Oct 27, 2026
Merged

JSON schema: move the element id mapping to docs.yaml and drop the legacy "id" keyword #3603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 1 addition & 10 deletions annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,16 +133,7 @@ private AbstractSchema<?> createParser(Model model, MainInfo main, ElementInfo e
parser = createRegularParser(model, main, elementInfo, parserName);
}

return tagElementId(parser, elementInfo);
}

@SuppressWarnings({ "rawtypes", "unchecked" })
private static AbstractSchema<?> tagElementId(AbstractSchema<?> schema, ElementInfo elementInfo) {
String id = elementInfo.getId();
if (id == null || id.isBlank()) return schema;

((AbstractSchema) schema).id(id);
return schema;
return parser;
}

private AbstractSchema<?> createNoEnvelopeParser(Model model, MainInfo main, ElementInfo elementInfo, String parserName) {
Expand Down
20 changes: 9 additions & 11 deletions annot/src/main/java/com/predic8/membrane/annot/generator/YamlDocsGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@

public class YamlDocsGenerator {

private static final int DOC_FORMAT_VERSION = 1;
private static final int DOC_FORMAT_VERSION = 2;
private static final String OUTPUT_FILE = "docs.yaml";

private static final ObjectMapper YAML_MAPPER = new ObjectMapper(
Expand Down Expand Up @@ -88,6 +88,7 @@ private Object buildRoot(Map<String, Map<String, ElementDoc>> byNamespace) {
if (ed.name != null && !ed.name.isBlank()) {
el.put("name", ed.name);
}
el.put("jsonSchemaDef", ed.jsonSchemaDef);
if (ed.doc != null && !ed.doc.isEmpty()) {
el.put("doc", ed.doc);
}
Expand Down Expand Up @@ -128,14 +129,15 @@ private Map<String, Map<String, ElementDoc>> collectMains(Model m) {
Map<String, Map<String, ElementDoc>> out = new TreeMap<>();

for (MainInfo main : m.getMains()) {
collect(main, out);
collect(m, main, out);
}

out.entrySet().removeIf(e -> e.getValue().isEmpty());
return out;
}

private void collect(MainInfo main, Map<String, Map<String, ElementDoc>> out) {
// Every element is listed, documented or not: the reference docs map JSON schema $defs keys to element ids through jsonSchemaDef.
private void collect(Model m, MainInfo main, Map<String, Map<String, ElementDoc>> out) {
Map<String, ElementDoc> elements = out.computeIfAbsent(main.getAnnotation().targetNamespace(), __ -> new TreeMap<>());

for (ElementInfo ei : main.getElements().values()) {
Expand All @@ -144,19 +146,14 @@ private void collect(MainInfo main, Map<String, Map<String, ElementDoc>> out) {
Map<String, Map<String, String>> children = childDocs(ei);
Map<String, String> otherAttrs = otherAttributesDoc(ei);

if (!isHasAnyDoc(elementDoc, attrs, children, otherAttrs)) continue;

elements.put(ei.getId(), getElementDoc(ei, elementDoc, attrs, children, otherAttrs));
elements.put(ei.getId(), getElementDoc(ei, ei.getXSDTypeName(m), elementDoc, attrs, children, otherAttrs));
}
}

private static boolean isHasAnyDoc(Map<String, String> elementDoc, Map<String, Map<String, String>> attrs, Map<String, Map<String, String>> children, Map<String, String> otherAttrs) {
return !elementDoc.isEmpty() || !attrs.isEmpty() || !children.isEmpty() || !otherAttrs.isEmpty();
}

private static @NotNull ElementDoc getElementDoc(ElementInfo ei, Map<String, String> elementDoc, Map<String, Map<String, String>> attrs, Map<String, Map<String, String>> children, Map<String, String> otherAttrs) {
private static @NotNull ElementDoc getElementDoc(ElementInfo ei, String jsonSchemaDef, Map<String, String> elementDoc, Map<String, Map<String, String>> attrs, Map<String, Map<String, String>> children, Map<String, String> otherAttrs) {
ElementDoc ed = new ElementDoc();
ed.name = ei.getAnnotation() != null ? ei.getAnnotation().name() : null;
ed.jsonSchemaDef = jsonSchemaDef;
ed.doc = elementDoc;
ed.attributes = attrs;
ed.children = children;
Expand Down Expand Up @@ -204,6 +201,7 @@ private Map<String, String> docMap(Doc doc) {

private static final class ElementDoc {
String name;
String jsonSchemaDef;
Map<String, String> doc = Map.of();
Map<String, Map<String, String>> attributes = Map.of();
Map<String, Map<String, String>> children = Map.of();
Expand Down
10 changes: 0 additions & 10 deletions ...t/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/AbstractSchema.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ public abstract class AbstractSchema<T extends AbstractSchema<T>> implements ISc

protected String title;
protected String name;
protected String id;
protected String type;
protected String description;
protected List<String> typeList;
Expand Down Expand Up @@ -77,11 +76,6 @@ public T name(String name) {
return self();
}

public T id(String id) {
this.id = id;
return self();
}

public T type(String type) {
this.type = type;
this.typeList = null;
Expand Down Expand Up @@ -117,10 +111,6 @@ public ObjectNode json(ObjectNode node) {
node.put("type", type);
}

if (id != null && !id.isBlank()) {
node.put("id", id);
}

return node;
}

Expand Down
12 changes: 0 additions & 12 deletions distribution/src/test/java/com/predic8/membrane/examples/ApisYamlSchemaValidationTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.MappingIterator;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
import com.networknt.schema.Error;
import com.networknt.schema.Schema;
Expand Down Expand Up @@ -74,7 +73,6 @@ class ApisYamlSchemaValidationTest {
if (in == null)
throw new IOException("Schema not found on classpath: " + SCHEMA_CLASSPATH);
JsonNode schemaNode = new ObjectMapper().readTree(in);
stripLegacyIdKeyword(schemaNode);
SchemaRegistry registry = SchemaRegistry.withDefaultDialect(DRAFT_2020_12);
SCHEMA = registry.getSchema(SchemaLocation.of(SCHEMA_CLASSPATH), schemaNode);
SCHEMA.initializeValidators();
Expand All @@ -83,16 +81,6 @@ class ApisYamlSchemaValidationTest {
}
}

private static void stripLegacyIdKeyword(JsonNode schemaNode) {
JsonNode defs = schemaNode.get("$defs");
if (defs == null)
return;
defs.forEach(def -> {
if (def instanceof ObjectNode obj)
obj.remove("id");
});
}

static Stream<String> getApisYamlConfigs() {
List<String> roots = List.of("examples", "tutorials");
return roots.stream()
Expand Down
Loading