Generate docs in a more compact way.

jsonschema/definitions/Concept.json

@@ -7,14 +7,32 @@
     {
       "type": "string",
       "title": "Concept",
-      "description": "The value of the concept, expressed as a string. This is only used when the concept is not further described by the properties of the Concept object and is not linked to a concept scheme."
+      "description": "The value of the concept, expressed as a string. This is only used when the concept is not further described by the properties of the Concept object and is not linked to a concept scheme.",
+      "examples": ["Environment", "Climate Science"]
     },
     {
       "type": "object",
+      "examples": [
+        {
+          "@type": "Concept",
+          "prefLabel": "Environment"
+        },
+        {
+          "@type": "Concept",
+          "prefLabel": "Climate Science",
+          "definition": "The scientific study of climate patterns and change.",
+          "inScheme": {
+            "@id": "https://example.gov/concept-schemes/science-domains",
+            "@type": "ConceptScheme",
+            "title": "Science Domains"
+          }
+        }
+      ],
       "properties": {
         "@id": {
           "type": "string",
-          "format": "iri"
+          "format": "iri",
+          "examples": ["https://example.gov/concepts/environment"]
         },
         "@type": {
           "type": "string",
@@ -23,17 +41,36 @@
         "altLabel": {
           "title": "alternate label",
           "description": "Alternative label for a concept",
-          "type": ["null", "string"]
+          "type": ["null", "string"],
+          "examples": ["Ecology"]
         },
         "definition": {
           "title": "definition",
           "description": "Definition of the controlled vocabulary term",
-          "type": ["null", "string"]
+          "type": ["null", "string"],
+          "examples": [
+            "The scientific study of climate patterns and change.",
+            "The natural world, including air, water, land, plants, and animals, especially as affected by human activity."
+          ]
         },
         "inScheme": {
           "title": "in scheme",
           "description": "Concept scheme defining this concept",
-          "$ref": "/dcat-us/3.0.0/definitions/conceptscheme"
+          "$ref": "/dcat-us/3.0.0/definitions/conceptscheme",
+          "examples": [
+            {
+              "@id": "https://example.gov/concept-schemes/science-domains",
+              "@type": "ConceptScheme",
+              "title": "Science Domains"
+            },
+            {
+              "@id": "https://example.gov/concept-schemes/data-themes",
+              "@type": "ConceptScheme",
+              "version": "2.0",
+              "description": "DCAT-US approved themes for categorizing datasets",
+              "title": "Data Themes"
+            }
+          ]
         },
         "notation": {
           "title": "notation",
@@ -48,12 +85,14 @@
                 "type": "string"
               }
             }
-          ]
+          ],
+          "examples": [["ENV", "E01", "ENVI"]]
         },
         "prefLabel": {
           "title": "preferred label",
           "description": "Preferred label for the term",
-          "type": "string"
+          "type": "string",
+          "examples": ["Environment", "Climate Science"]
         }
       },
       "required": ["prefLabel"]
@@ -62,5 +101,38 @@
   "_oldDocs": {
     "rdfClass": "skos:Concept",
     "rationale": "The inclusion of skos:Concept in DCAT-US 3.0 enhances semantic search in catalogs, enabling more accurate discovery of Catalogs, Datasets, and Data Services. It improves user experience, promotes data discoverability, and supports better resource utilization. Additionally, it aligns with international standards like SKOS, ensuring compatibility and adherence to recognized controlled vocabulary practices."
-  }
+  },
+  "examples": [
+    "Environment",
+    "Climate Science",
+    {
+      "@type": "Concept",
+      "prefLabel": "Environment"
+    },
+    {
+      "@type": "Concept",
+      "prefLabel": "Climate Science",
+      "definition": "The scientific study of climate patterns and change.",
+      "inScheme": {
+        "@id": "https://example.gov/concept-schemes/science-domains",
+        "@type": "ConceptScheme",
+        "title": "Science Domains"
+      }
+    },
+    {
+      "@id": "https://example.gov/concepts/environment",
+      "@type": "Concept",
+      "prefLabel": "Environment",
+      "altLabel": "Ecology",
+      "definition": "The natural world, including air, water, land, plants, and animals, especially as affected by human activity.",
+      "notation": ["ENV", "E01", "ENVI"],
+      "inScheme": {
+        "@id": "https://example.gov/concept-schemes/data-themes",
+        "@type": "ConceptScheme",
+        "version": "2.0",
+        "description": "DCAT-US approved themes for categorizing datasets",
+        "title": "Data Themes"
+      }
+    }
+  ]
 }

jsonschema/doc_templates/md/content.md

@@ -14,7 +14,7 @@
 {% set keys = schema.keywords %}
 {%- if not skip_headers %}
 
-{% if schema.title and schema.title | length > 0 %}
+{% if schema | should_render_title %}
 **Title:** {{ schema.title }}
 {% endif %}
 
@@ -30,31 +30,30 @@
     {% include "section_examples.md" %}
 {% endif %}
 
+{# If this is a reference, do not expand inline #}
 {% if schema.should_be_a_link(config) %}
+    {# Only show the canonical link, not inline details #}
 {% elif schema.refers_to -%}
-    {# If it's referred to, we're linking to it, not including it here. #}
-    {%- with schema=schema.refers_to_merged, skip_headers=True, depth=depth -%}
-        {# include "content.md" #}
-    {% endwith %}
+    {# Only show the canonical link, not inline details #}
 {% else %}
     {# Properties, pattern properties, additional properties #}
     {% if schema.is_object %}
-    {{- schema | md_properties_table | md_generate_table -}}
+        {{- schema | md_properties_table | md_generate_table -}}
     {% endif %}
 
     {# Combining: allOf, anyOf, oneOf, not #}
     {% if schema.kw_all_of %}
-        {% with operator="allOf", title="All of(Requirement)", current_node=schema.kw_all_of, skip_required=True %}
+        {% with operator="allOf", title="All of", current_node=schema.kw_all_of, skip_required=True %}
             {% include "tabbed_section.md" %}
         {% endwith %}
     {% endif %}
     {% if schema.kw_any_of %}
-        {% with operator="anyOf", title="Any of(Option)", current_node=schema.kw_any_of, skip_required=True %}
+        {% with operator="anyOf", title="Any of", current_node=schema.kw_any_of, skip_required=True %}
             {% include "tabbed_section.md" %}
         {% endwith %}
     {% endif %}
     {% if schema.kw_one_of %}
-        {% with operator="oneOf", title="One of(Option)",current_node=schema.kw_one_of, skip_required=True %}
+        {% with operator="oneOf", title="One of", current_node=schema.kw_one_of, skip_required=True %}
             {% include "tabbed_section.md" %}
         {% endwith %}
     {% endif %}
@@ -90,6 +89,12 @@
 
     {# details of Properties, pattern properties, additional properties #}
     {% if schema.is_object %}
-    {% include "section_properties_details.md" %}
+        {% include "section_properties_details.md" %}
     {% endif %}
 {% endif %}
+
+{# Placeholder for See Also section for main classes #}
+{% if schema.title in ["Catalog", "Dataset", "Dataset Series", "Distribution"] %}
+---
+**See Also:** (related supporting classes)
+{% endif %}

jsonschema/doc_templates/md/section_array.md

@@ -1,39 +1,50 @@
+
 {{ schema | md_array_restrictions | md_generate_table }}
 
+{# Only show array items table; suppress inline details if canonical link exists #}
 {% if schema.array_items_def or schema.tuple_validation_items %}
 {{ schema | md_array_items_restrictions | md_generate_table }}
 {% endif %}
 
+{# Only expand inline details for array items if not a reference/canonical link #}
 {% if schema.array_items_def %}
-{% filter md_heading(depth+1, schema.array_items_def.html_id) %}
-{% with schema=schema.array_items_def %}{%- include "breadcrumbs.md" %}{% endwith %}
-{% endfilter %}
-{% with schema=schema.array_items_def, skip_headers=False, depth=depth+1, skip_required=True %}
-    {% include "content.md" %}
-{% endwith %}
+    {% set is_linked_array_item = schema.array_items_def.should_be_a_link(config) or schema.array_items_def.refers_to %}
+    {% if not is_linked_array_item %}
+        {% filter md_heading(depth+1, schema.array_items_def.html_id) %}
+            {{ schema.array_items_def.title or 'Array Item' }}
+        {% endfilter %}
+        {% with schema=schema.array_items_def, skip_headers=False, depth=depth+1, skip_required=True %}
+            {% include "content.md" %}
+        {% endwith %}
+    {% endif %}
 {% endif %}
 
+{# Tuple validation items: only expand if not a reference #}
 {% if schema.tuple_validation_items %}
-{% for item in schema.tuple_validation_items %}
-    {% filter md_heading(depth+1) %}
-    {% with schema=item %}{%- include "breadcrumbs.md" %}{% endwith %}
-    {% endfilter %}
-    {% with schema=item, skip_headers=False, depth=depth+1, skip_required=True %}
-        {% include "content.md" %}
-    {% endwith %}
-{% endfor %}
+    {% for item in schema.tuple_validation_items %}
+        {% set is_linked_tuple_item = item.should_be_a_link(config) or item.refers_to %}
+        {% if not is_linked_tuple_item %}
+            {% filter md_heading(depth+1) %}
+                {{ item.title or 'Tuple Item' }}
+            {% endfilter %}
+            {% with schema=item, skip_headers=False, depth=depth+1, skip_required=True %}
+                {% include "content.md" %}
+            {% endwith %}
+        {% endif %}
+    {% endfor %}
 {% endif %}
 
+{# Contains/Additional items unchanged for now #}
 {% if schema.kw_contains and schema.kw_contains.literal != {} %}
-{{ "At least one of the items must be" | md_heading(depth+1) }}
-{% with schema=schema.kw_contains, skip_headers=False, depth=depth+1, skip_required=True %}
-    {% include "content.md" %}
-{% endwith %}
+    {{ "At least one of the items must be" | md_heading(depth+1) }}
+    {% with schema=schema.kw_contains, skip_headers=False, depth=depth+1, skip_required=True %}
+        {% include "content.md" %}
+    {% endwith %}
 {% endif %}
 
 {% if schema.array_additional_items_def %}
-{{ "Additional items must be" | md_heading(depth+1) }}
-{% with schema=schema.array_additional_items_def, skip_headers=False, depth=depth+1, skip_required=True %}
-    {% include "content.md" %}
-{% endwith %}
+    {{ "Additional items must be" | md_heading(depth+1) }}
+    {% with schema=schema.array_additional_items_def, skip_headers=False, depth=depth+1, skip_required=True %}
+        {% include "content.md" %}
+    {% endwith %}
 {% endif %}

jsonschema/doc_templates/md/section_examples.md

@@ -1,16 +1,16 @@
 **Example{% if examples|length > 1 %}s{% endif %}:**{{- "" -}}
 
 {% for example in examples %}
-    {%- if loop.first %}{{ "\n\n" }}{% endif -%}
-    {% set example_id = schema.html_id ~ "_ex" ~ loop.index %}
-    {%- if not examples_as_yaml -%}
-        {{- "" }}```json
-        {{- "\n" }}{{ example }}
-        {{- "\n" }}```
-    {%- else -%}
-        {{- "" }}```yaml
-        {{- "\n" }}{{ example | yaml_example }}
-        {{- "\n" }}```
-    {%- endif -%}
-    {{ "\n" }}
+	{%- if loop.first %}{{ "\n\n" }}{% endif -%}
+	{% set example_id = schema.html_id ~ "_ex" ~ loop.index %}
+	{%- if not examples_as_yaml -%}
+		{{- "" }}```json
+		{{- "\n" }}{{ example }}
+		{{- "\n" }}```
+	{%- else -%}
+		{{- "" }}```yaml
+		{{- "\n" }}{{ example | yaml_example }}
+		{{- "\n" }}```
+	{%- endif -%}
+	{{ "\n" }}
 {% endfor %}

jsonschema/doc_templates/md/section_one_of.md

@@ -1,4 +1,13 @@
 Must be one of:
 {% for enum_choice in schema.kw_enum.array_items %}
 * {{ enum_choice.literal | python_to_json }}
-{% endfor %}
+{% endfor %}
+
+{# If there are subschemas with details, show them compactly #}
+{% if schema.kw_one_of or schema.kw_any_of %}
+	{% for subschema in (schema.kw_one_of or schema.kw_any_of) %}
+		{% if subschema.title or subschema.description %}
+			- **{{ subschema.title or 'Option' }}**: {{ subschema.description or '' }}
+		{% endif %}
+	{% endfor %}
+{% endif %}

jsonschema/doc_templates/md/section_properties_details.md

@@ -4,18 +4,13 @@
   {% endif %}
 
   {% set html_id = sub_property.html_id %}
-
   {% set description = sub_property | get_description %}
 
+  {# Keep property headings minimal; requirement appears in the body below. #}
   {% filter md_heading(depth + 1, html_id) -%}
-    {%- filter replace('\n', '') -%}
-      {%- if not skip_required and sub_property.property_name -%}
-        {{ sub_property | requirement_badge -}}{{ ' ' }}
-      {%- endif -%}
-      {%- if sub_property is deprecated  -%}~~ {%- endif -%}
-      {%- if sub_property.is_pattern_property %}Pattern {% endif %}Property `{% with schema=sub_property %}{%- include "breadcrumbs.md" %}{% endwith %}`
-      {%- if sub_property is deprecated -%}~~{%- endif -%}
-    {%- endfilter %}
+    {%- if sub_property is deprecated  -%}~~ {%- endif -%}
+    `{% with schema=sub_property %}{%- include "breadcrumbs.md" %}{% endwith %}`
+    {%- if sub_property is deprecated -%}~~{%- endif -%}
   {%- endfilter %}
 
   {% if sub_property.is_pattern_property %}
@@ -24,7 +19,6 @@
 must respect the following conditions
   {% endif %}
 
-
   {% with schema=sub_property, skip_headers=False, depth=depth+1 %}
     {% include "content.md" %}
   {% endwith %}

jsonschema/doc_templates/md/tabbed_section.md

@@ -3,7 +3,7 @@
 
 {% for node in current_node.array_items %}
     {% filter md_heading(depth+1, node.html_id) -%}
-        {% if node.is_pattern_property %}Pattern{% endif %} Property `{% with schema=node %}{%- include "breadcrumbs.md" %}{% endwith %}`
+        {% if node.is_pattern_property %}Pattern {% endif %}`{% with schema=node %}{%- include "breadcrumbs.md" %}{% endwith %}`
     {%- endfilter %}
     {% with schema=node, skip_headers=False, depth=depth+1 %}
         {% include "content.md" %}