Documented example schema for SOS guide

.tools/validation/schema/example_schema.yaml

@@ -3,36 +3,58 @@
 
 map(include('example'), key=example_id())
 ---
+# An example blocks all the languages together for a single example in a tab list. It is a navigable page on the code examples library. It is the top level "unit" of SoS content. This metadata is merged from tributaries with aws-doc-sdk-examples.
 example:
-  title: str(upper_start=True, no_end_punc=True)
-  title_abbrev: str(upper_start=True, no_end_punc=True)
-  synopsis: str(required=False, lower_start=True, end_punc_or_semicolon=True)
-  synopsis_list: list(str(upper_start=True, end_punc=True), required=False)
-  category: str(required=False, upper_start=True, no_end_punc=True)
-  guide_topic: include('guide_topic', required=False)
+  # Human readable title, defaulting to slug-to-title of the ID if not provided. Overwritten by aws-doc-sdk-example when merging.
+  title: str(upper_start=True, no_end_punc=True, required=False)
+  # Used in the TOC, defaults to slug-to-title of the ID if not provided. Overwritten by aws-doc-sdk-example when merging.
+  title_abbrev: str(upper_start=True, no_end_punc=True, required=False)
+  # String label categories. Categories inferred by cross-service with multiple services, and can be whatever else it wants. Controls where in the TOC it appears. Overwritten by aws-doc-sdk-example when merging.
+  category: str(required=False, upper_start=True, no_end_punc=True, required=False)
+  # Link to additional topic places. Overwritten by aws-doc-sdk-example when merging.
+  guide_topic: include('guide_topic', required=False) # TODO Make this a list or a single.
+  # TODO how to add a language here and require it in sdks_schema. Keys merged by aws-doc-sdk-example when merging.
   languages: map(include('language'), key=enum('Bash', 'C++', 'CLI', 'Go', 'Java', 'JavaScript', 'Kotlin', '.NET', 'PHP', 'Python', 'Ruby', 'Rust', 'SAP ABAP', 'Swift'))
+  # TODO document. Not to be used by tributaries. Part of Cross Service.
   service_main: service_name(required=False)
+  # TODO document. Not to be used by tributaries. Part of Cross Service.
+  # List of services used by the examples. Lines up with those in services.yaml. Overwritten by aws-doc-sdk-example when merging.
   services: map(map(key=str(), required=False), key=service_name())
+  synopsis: str(required=False, lower_start=True, end_punc_or_semicolon=True, required=False)
+  synopsis_list: list(str(upper_start=True, end_punc=True), required=False)
 
+# Used for creating links in the block.
 guide_topic:
   title: str(upper_start=True, no_end_punc=True)
   url: include('doc_url', required=False)
 
+# Language Version configuration. Likely just the single list item.
 language:
   versions: list(include('version'))
 
+# Example for a single Language.
 version:
   sdk_version: int(min=1)
-  github: regex('^(?!http).+', name="relative URL", required=False)
-  sdkguide: include('doc_url', required=False)
-  excerpts: list(include('excerpt'), required=False)
+  # Additional ZonBook XML to include in the tab for this sample.
   block_content: block_content(required=False)
+  # The specific code samples to include in the example.
+  excerpts: list(include('excerpt'), required=False)
+  # Link to the source code for this example. TODO rename.
+  github: str(required=False)
   add_services: map(key=service_name(), required=False)
+  # Deprecated. Replace with guide_topic list.
+  sdkguide: include('doc_url', required=False)
+  # Link to additional topic places. Overwritten by aws-doc-sdk-example when merging.
+  more_info: list(include('guide_topic', required=False))
 
+# One language example can have several excerpts, each having a description block and one or more snippets.
+# An excerpt may have either snippet_files OR snippet_tags, but not both.
 excerpt:
   description: str(required=False, upper_start=True, end_punc=True)
-  snippet_tags: list(str(), required=False)
+  # A path within the repo to extract the entire file as a snippet.
   snippet_files: list(str(), required=False)
+  # Tags embedded in source files to extract as snippets.
+  snippet_tags: list(str(), required=False)
 
 service_slug_regex: regex('^[\da-z-]+$', name='service slug')
 doc_url: regex('^(?!https://docs.aws.amazon.com/).+', name="relative documentation URL")

.tools/validation/schema/example_strict_schema.yaml

@@ -0,0 +1,40 @@
+# Yamale Schema for example metadata, which is all .yaml files in the metadata folder
+# with a _metadata.yaml suffix.
+
+map(include('example'), key=example_id())
+---
+example:
+  title: str(upper_start=True, no_end_punc=True)
+  title_abbrev: str(upper_start=True, no_end_punc=True)
+  synopsis: str(required=False, lower_start=True, end_punc_or_semicolon=True)
+  synopsis_list: list(str(upper_start=True, end_punc=True), required=False)
+  category: str(required=False, upper_start=True, no_end_punc=True)
+  guide_topic: include('guide_topic', required=False)
+  languages: map(include('language'), key=enum('Bash', 'C++', 'CLI', 'Go', 'Java', 'JavaScript', 'Kotlin', '.NET', 'PHP', 'Python', 'Ruby', 'Rust', 'SAP ABAP', 'Swift'))
+  service_main: service_name(required=False)
+  services: map(map(key=str(), required=False), key=service_name())
+
+guide_topic:
+  title: str(upper_start=True, no_end_punc=True)
+  url: include('doc_url', required=False)
+
+language:
+  versions: list(include('version'))
+
+# Per-language excerpts for the example. Languages and SDK versions are defined in .doc_gen/metadata/sdk_metadata.yaml
+version:
+  sdk_version: int(min=1)
+  github: regex('^(?!http).+', name="relative URL", required=False)
+  sdkguide: include('doc_url', required=False)
+  excerpts: list(include('excerpt'), required=False)
+  block_content: block_content(required=False)
+  add_services: map(key=service_name(), required=False)
+
+# The references to code content that will be included in the example's content.
+excerpt:
+  description: str(required=False, upper_start=True, end_punc=True)
+  snippet_tags: list(str(), required=False)
+  snippet_files: list(str(), required=False)
+
+service_slug_regex: regex('^[\da-z-]+$', name='service slug')
+doc_url: regex('^(?!https://docs.aws.amazon.com/).+', name="relative documentation URL")

.tools/validation/validate_doc_metadata.py

@@ -204,7 +204,8 @@ def validate_all(doc_gen: Path):
     success &= validate_files(schema_name, meta_names, validators)
 
     # Validate example (*_metadata.yaml in metadata folder) files.
-    schema_name = schema_root / "example_schema.yaml"
+    # TODO: Switch between strict schema for aws-doc-sdk-examples and loose schema for tributaries
+    schema_name = schema_root / "example_strict_schema.yaml"
     meta_names = glob.glob(os.path.join(doc_gen, "metadata/*_metadata.yaml"))
     success &= validate_files(schema_name, meta_names, validators)