Potential guest post about rendering data definition tables using yaml2text

[ronaldtse]

Potential guest post from @stuartgalt 😉

issue-385.zip

Output:
issue-385.pdf

The files are:

• document.adoc: holder of content that includes the [yaml2text] block.
• data_definition_table.liquid: Liquid template that renders the data definition into an AsciiDoc table.
• Entity_schema_definition.yaml: Data definition of the Entity_schema_definition object.

document.adoc

Holder of content that includes the [yaml2text] block.

...

== Content

[yaml2text,Entity_schema_definition.yaml,context]
----
include::./data_definition_table.liquid[]
----

data_definition_table.liquid

Liquid template that renders the data definition into an AsciiDoc table.

// The data context passed in is called `context`.

{% liquid
assign table_name = context.name
assign table_anchor = "tab-" | concat: context.name | replace " ", "_"
%}
[[{{ table_anchor }}]]
.{{ table_name }}
|===
| Name | Data Type | Data Description

{% for item in context.attributes %}
| *{{ item.name }}*

{% case item.data_type.kind %}
{% when "Array" %}
| Array _<{{ item.data_type.inner_kind }}>_[*{{ item.data_type.occurrence }}*]
{% else %}
| _{{ item.data_type.kind }}_
{% endcase %}

| {% if item.required %}(Required){% else %}(Optional){% endif %}
{{ item.description }}

{% endfor %}
|===

Entity_schema_definition.yaml

Data definition of the Entity_schema_definition object.

Entity_schema_definition.yaml

---
name: Entity_schema_definition
attributes:
- name: entity_type
  data_type:
    kind: UnsignedInteger
  description: entity_type represents the entity type, that is being described by the array of schema tokens.
  required: true
- name: token_count
  data_type:
    kind: UnsignedInteger
  description: Number of tokens describing this entity type
  required: true
- name: schema_tokens
  data_type:
    kind: Array
    inner_kind: UnsignedInteger
    occurrence: token_count
  description: Array of schema tokens describing this entity type
  required: true

Afterthoughts

If you'd like to apply this to multiple tables you could use Arnaud's approach here with nested blocks:

• https://www.metanorma.org/blog/2024-03-31-developing-itu-t-recommendations/

Which would look like this

=== Data definitions
[yaml2text,sections/paths.yaml,data] (1)
----
{% for path in data.paths %}
[yaml2text, {{ path }}, profile]
--
include::./data_definition_table.liquid[]
--
{% endfor %}
----

Where sections/profiles.json is a list of YAML file paths to be read.

Originally posted by @ronaldtse in metanorma/metanorma#385 (comment)