# WireViz YAML Schema for syntax validation using Yamale
connectors: map(include('CONNECTOR')) # dictionary of all used connectors
cables: map(include('CABLE')) # dictionary of all used cables and wires
connections: list(include('CONNECTION')) # list of all connections to be  made
additional_bom_items: list(include('additional_bom-item'), required=False) # custom items to add to BOM
metadata: include('metadata', required=False) # dictionary of meta-information describing the harness
options: include('option', required=False) # dictionary of common attributes for the whole harness
tweak: include('tweak', required=False) # optional tweaking of .gv output
---
DESIGNATOR: regex('^[a-zA-Z\200-\377_-][0-9a-zA-Z\200-\377_\\.]*$', name='designator', multiline=False)
---
CONNECTOR: # unique connector designator/name
  # pinout information
  # at least one of the following must be specified
  pincount: int(min=1, required=False) # if omitted, is set to length of specified list(s)
  pins: list(required=False) # if omitted, is autofilled with [1, 2, ..., pincount]
  pinlabels: list(required=False) # if omitted, is autofilled with blanks
  # pin color marks (optional)
  pincolors: list(required=False) # list of colors to be assigned to the respective pins;
  # if list length is lower than connector pinout,
  # no color marks will be added to remaining pins

  # general information about a connector (all optional)
  type: str(required=False)
  subtype: str(required=False)
  color: include('colorname', required=False) # see below
  image: include('image', required=False)
  notes: str(required=False)
  # product information (all optional)
  ignore_in_bom: bool(required=False) # if set to true the connector is not added to the BOM
  pn: subset(int(),str(),allow_empty=True) # [internal] part number
  manufacturer: str(required=False) # manufacturer name
  mpn: subset(int(),str(),allow_empty=True) # manufacturer part number
  supplier: str(required=False) # supplier name
  spn: subset(int(),str(),allow_empty=True) # supplier part number
  additional_components: list(include('additional_component'), required=False) # additional components

  # rendering information (all optional)
  bgcolor: include('colorname', required=False) # Background color of diagram connector box
  bgcolor_title: include('colorname', required=False) # Background color of title in diagram connector box
  style: str(equals='simple', required=False) # may be set to simple for single pin connectors
  show_name: bool(required=False) # defaults to true for regular connectors, false for simple connectors
  show_pincount: bool(required=False) # defaults to true for regular connectors false for simple connectors
  hide_disconnected_pins: bool(required=False) # defaults to false

  loops: list(required=False) # every list item is itself a list of exactly two pins on the connector that are to be shorted
---
CABLE: # unique cable designator/name
  # conductor information
  # the following combinations are permitted:
  # wirecount only          no color information is specified
  # colors only             wirecount is inferred from list length
  # wirecount + color_code  colors are auto-generated based on the specified
  #                         color code (see below) to match the wirecount
  # wirecount + colors      colors list is trimmed or repeated to match the wirecount
  wirecount: int(min=1, required=False)
  colors: list(required=False) # list of colors (see below)
  color_code: include('colorcode', required=False) # one of the supported cable color codes (see below)

  wirelabels:
    list(required=False) # optional; one label for each wire
    # general information about a connector (all optional)
  category: str(equals='bundle', required=False) # may be set to bundle;
  # generates one BOM item for every wire in the bundle
  # instead of a single item for the entire cable;
  # renders with a dashed outline
  type: str(required=False)
  gauge: subset(int(), num(), str(min=1), allow_empty=True) # allowed formats:
  # num() mm2 is understood
  # int() AWG is understood
  # num() is assumed to be mm2
  # str() custom units and formats are allowed but unavailable for auto-conversion
  show_equiv: bool(required=False) # defaults to false; can auto-convert between mm2 and AWG and display the result when set to true
  length: subset(num(), str(min=1), allow_empty=True) # num() is assumed to be in meters unless <unit> is specified
  # e.g. length: 2.5 -> assumed to be 2.5 m
  # or   length: 2.5 ft -> "ft" is used as the unit
  # Units are not converted during BOM generation;
  # different units result in separate BOM entries.
  shield: subset(bool(), include('colorname'), allow_empty=True) # defaults to false
  # setting to true will display the shield as a thin black line
  # using a color (see below) will render the shield in that color
  # A shield can be accessed by using 's' as the wire ID
  color: include('colorname', required=False) # see below
  image: include('image', required=False)
  notes: str(required=False)

  # product information (all optional)
  ignore_in_bom: bool(required=False) # if set to true the cable or wires are not added to the BOM
  pn: subset(int(),str(),allow_empty=True) # [internal] part number
  manufacturer: subset(str(required=False),allow_empty=True) # manufacturer name
  mpn: subset(int(),str(),allow_empty=True) # manufacturer part number
  supplier: subset(str(),allow_empty=True) # supplier name
  spn: subset(int(),str(),allow_empty=True) # supplier part number
  additional_components: list(include('additional_component'), required=False) # additional components

  # rendering information (all optional)
  bgcolor: include('colorname', required=False) # Background color of diagram cable box
  bgcolor_title: include('colorname', required=False) # Background color of title in diagram cable box
  show_name: bool(required=False) # defaults to true
  show_wirecount: bool(required=False) # defaults to true
  show_wirenumbers: bool(required=False) # defaults to true for cables; false for bundles
---
CONNECTION: list(any(include('DESIGNATOR'),list(include('DESIGNATOR')),map(),enum('--','<--','<-->','-->','==','<==','<==>','==>')),required=False) # list of all connections to be made
---
additional_bom-item: # custom items to add to BOM
  description: str()
  # all the following are optional:
  qty: num(required=False) # qty to add to the bom (defaults to 1)
  unit: str(required=False)
  designators: list(include('DESIGNATOR'), required=False)
  pn: subset(int(),str(),allow_empty=True) # [internal] part number
  manufacturer: str(required=False) # manufacturer name
  mpn: subset(int(),str(),allow_empty=True) # manufacturer part number
  supplier: str(required=False) # supplier name
  spn: subset(int(),str(),allow_empty=True) # supplier part number
---
additional_component:
  type: str() # type of additional component
  # all the following are optional:
  subtype: str(required=False) # additional description (only shown in bom)
  qty: num(required=False) # qty to add to the bom (defaults to 1)
  qty_multiplier: str(required=False) # multiplies qty by a feature of the parent component
  # when used in a connector:
  # pincount         number of pins of connector
  # populated        number of populated positions in a connector
  # unpopulated      number of unpopulated positions
  # when used in a cable:
  # wirecount        number of wires of cable/bundle
  # terminations     number of terminations on a cable/bundle
  # length           length of cable/bundle
  # total_length     sum of lengths of each wire in the bundle
  unit: str(required=False)
  pn: subset(int(),str(),allow_empty=True) # [internal] part number
  manufacturer: str(required=False) # manufacturer name
  mpn: subset(int(),str(),allow_empty=True) # manufacturer part number
  supplier: str(required=False) # supplier name
  spn: subset(int(),str(),allow_empty=True) # supplier part number
  bgcolor: include('colorname', required=False) # Background color of entry in diagram component box
---
metadata: map(key=str(), required=False) # dictionary of meta-information describing the harness
# Each key/value pair replaces all key references in
# the HTML output template with the belonging value.
# Typical keys are 'title', 'description', and 'notes',
# but any key is accepted. Unused keys are ignored.
#<key>   : <value>  # Any valid YAML syntax is accepted
# If no value is specified for 'title', then the
# output filename without extension is used.
---
option: # dictionary of common attributes for the whole harness
  # Common attributes for the whole harness.
  # All entries are optional and have default values.

  # Background color of diagram and HTML output
  bgcolor: include('colorname', required=False) # Default = 'WH'

  # Background color of other diagram elements
  bgcolor_node: include('colorname', required=False) # Default = 'WH'
  bgcolor_connector: include('colorname', required=False) # Default = bgcolor_node
  bgcolor_cable: include('colorname', required=False) # Default = bgcolor_node
  bgcolor_bundle: include('colorname', required=False) # Default = bgcolor_cable

  # How to display colors as text in the diagram
  # 'full' : Lowercase full color name
  # 'FULL' : Uppercase full color name
  # 'hex'  : Lowercase hexadecimal values
  # 'HEX'  : Uppercase hexadecimal values
  # 'short': Lowercase short color name
  # 'SHORT': Uppercase short color name
  # 'ger'  : Lowercase short German color name
  # 'GER'  : Uppercase short German color name
  color_mode: enum('full','FULL','hex','HEX','short','SHORT','ger','GER', required=False)

  # Fontname to use in diagram and HTML output
  fontname: str(required=False) # Default = 'arial'

  # If True, show only a BOM entry reference together with basic info
  # about additional components inside the diagram node (connector/cable box).
  # If False, show all info about additional components inside the diagram node.
  mini_bom_mode: bool(required=False) # Default = True
---
tweak: # optional tweaking of .gv output
  # Optional tweaking of the .gv output.
  # This feature is experimental and might change
  # or be removed in future versions.

  override: subset(map(required=False),allow_empty=True) # dict of .gv entries to override
  # Each entry is identified by its leading string
  # in lines beginning with a TAB character.
  # The leading string might be in "quotes" in
  # the .gv output. This leading string must be
  # followed by attributes in [square brackets].
  # Entries with an attribute containing HTML are
  # not supported.
  # str():  # leading string of .gv entry
  #   str() : <str/null>  # attribute and its new value
  # Any number of attributes can be overridden
  # for each entry. Attributes not already existing
  # in the entry will be appended to the entry.
  # Use null as new value to delete an attribute.

  append: any(str(),list(),required=False) # string or list of strings to append to the .gv output
---
colorname: any(enum('BK','WH','GY','PK','RD','OG','YE','OL','GN','TQ','LB','BU','VT','BN','BG','IV','SL','CU','SN','SR','GD'),regex('#[0-9A-Fa-f]{6}',name='html_color'))
colorcode: enum('DIN', 'IEC', 'TEL', 'TELALT', 'T568A', 'T568B', 'BW')
---
image:
  src: str() # path to the image file
  # optional parameters:
  caption: str(required=False) # text to display below the image
  bgcolor: include('colorname', required=False) # Background color of entry in diagram component box
  width: int(required=False) # range: 1~65535; unit: points
  height: int(required=False) # range: 1~65535; unit: points
  # if only one dimension (width/height) is specified, the image is scaled proportionally.
  # if both width and height are specified, the image is stretched to fit.