Class element

A class element is an associative array that holds information about a class. It has the following keys:

• id: mandatory, string. The id of the class. Class ids are one word identifiers, which must be unique within the repository. This class id is used as a way to refer to the class, when the standard field is not set. They must contain only letters, numbers and underscores.
• names: optional, class-name-element or list of class-name-element . One or several names for this class.
• standards: optional, class-standard-element or list of class-standard-element . One or several standards, in which the parts of this class are specified.
• parameters: optional, parameter-element: Parameters for this class.
• url: optional, string or list of strings. A url with relevant information regarding the parts of this class. For example a link to a vendor, or to the specifying standard. In the case of several identical standards, a list of urls has to be given.
• notes: optional, string. Notes for this class. Can be used to keep questions or additional information.
• source: mandatory, string. A short description where the information for this class originate. Should contain a URL if possible.

Class Name Element

A class name element is a way to assign a name to a class. A class element should be used for general names, like "Hex head screws" and for names that are not derived from a standard issued by a standardisation body. For names that are derived from a standard, a class-standard-element is more appropriate.

A class name element is an associative array with the following keys:

• name: mandatory, string or identifier-element. The name for the class. If given as a string, this is interpreted as the nice name of the identifier element.
• group: optional, string or identifier-element. Can be used to group class names together, similar to the group in a class-standard-element. Useful for parts that are not standardized by a standardisation body, but by e.g. a vendor. If given as a string is taken as the nice name of the identifier element.
• labeling: mandatory, string or substitution-element. A template for the name of a part from this class, e.g. for a BOM. If given as string is taken to be the nice name.
• description: optional, string. A short description of the class.

The safe name of this class must be unique within the repository and provides a way to refer to this class.

Class Standard Element

A class standard element is similar to a class-name-element, but is used specifically to associate a class with a formal standard, and allows to expresses additional facts about this standard.

a class standard element is an associative array with the following keys:

• standard: mandatory, string or identifier-element. The name of the standard. If given as a string is taken as the nice name of an identifier element.
• group: optional, string or identifier-element. If a single standard specifies multiple classes of parts, the group can be used to collect the substandards together. If the group is given as a string is taken as the nice name of the identifier element.
• labeling: mandatory, string or substitution-element. A template for the name of a part from this class, e.g. for a BOM. If given as a string is taken as the nice name.
• body: mandatory, string. The standardisation body that issued the standard.
• year: optional, integer. The year in which the standard was issued.
• status: optional, string. This can be used to indicate the status of the standard. Possible values are "active" and "withdrawn", if absent, "active" is assumed.
• replaces: optional, string. Names of ths standards that are superseded by this standard.
• description: optional, string. A short description of the class.

If a group field is specified it has to be identical in all standards that belong to this group. In this case the standard fields have to contain a suffix or similar to distinguish them from the group, while still being unique. If several classes are specified in the same standard, the safe and nice names of the corresponding class standard elements must be the same in all classes. .. not sure I still understand this last sentence.

Identifier element

To be able to uniquely refer to class in different circumstances, it is necessary to have both a safe and a nice name. The former is used in file names or as function or variable name in a script, and therefore has to obey certain constraints. The latter is used in places, where no such constraints apply, like GUIs or web pages.

These two names are bundled up in a identifier-element, an associative array with the following keys:

• nice: mandatory, string. A nice name for the class.
• safe: optional, string. A safe name for the class. This means, it contains only alphanumerical characters and underscores. Defaults to a sanitized version of the nice name.

Substitution element

One also wants to have name or labels for a part derived from a class. This name usually depends on the value of the parameters and, like with the identifier-element, must be available in a safe and nice form for use in different situations. The restrictions on the safe name are a bit weaker than with the identifier-element.

To insert the value of a parameter into this name, a placeholder of the form %(parameter)s can be inserted.

• nice: mandatory, string. A nice name for the part.
• safe: mandatory, string. A safe name for the class. This means they must be ASCII printable with no forward or backward slashes, no question marks, no asterisk, no colon, no pipe, no quotes, no lesser or greater than signs, no whitespace. Defaults to a sanitized version of the nice name.

Parameter element

A parameter element is an associative array that holds information about the parameters of a part. This information is used when doing parameter-collection. Parameters are often dimensions, but are not restricted to be. The following keys are contained in a parameter element.

• literal: optional, associative array. This array has as its key the parameter names of the literal parameters, as values the corresponding values. Literal parameters are rarely used.
• free: optional, list. This list contains the names of the parameters for which the user will provide this value.
• tables: optional, table-element or list of table-elements. This array contains tabular data. Usually the table index will be a free variable, for details see table-element and parameter-collection.
• tables2d: optional, table2d-element or list of table2d-elements. This array contains tabular data. Usually row and column indices will be free variables, for details see table2d-element and parameter-collection.
• types: mandatory, associative array. Contains as keys parameter names, as values their respective types. Possible types are: "Length (mm)", Length (in)", "Number", "Bool", "Table Index", "String", "Angle (deg)".
• defaults: optional, associative array. This array contains a default value for every free parameter. If absent, the default value defaults to the type specific values given in the table below.
• description: optional, associative array. This array contains short a short text for each parameter clarifying the meaning of the parameter in plain language.
• common: optional, list of lists of (lists or strings). This field contains a list of tuples that contain valaues for all free parameters in the order in which they are given in the free field. These tuples are represented by a YAML list and contain common combinations of parameters. For more compact notation, every element of the tuple actually is a list of values, so the tuple represents all possible combinations of values for the parameters. A tuple element can also be ":" if the free variable is discrete (see table below), the being a shorthand for all possible values. Defaults to the empty list, if at least one free variable is not discrete. If all free variables are discrete, the default is the tuple with all possible parameter combinations.

The two values of the type Bool are true and false (lowercase). Table index values (keys) are strings, and must be ASCII with no forward or backward slashes, no question marks, no asterisk, no colon, no pipe, no quotes, no lesser or greater than signs.

Table element

Tables of data are very common in standards and very useful for specifying a class of parts. A table element describes a table of values, where the row is specified by the value of an index parameter, and each column contains the value for a parameter. A table element is an associative array that has the following keys:

• index: mandatory, string: name of the index parameter. Has to specified to be of type "Table Index" in the parameter-element.
• columns: mandatory, list of strings: list of parameter names corresponding to the columns of the table.
• data: mandatory, associative array: The keys are possible values of the index parameter, the values a list of values compatible with the types of the parameters specified in columns. Note the restriction on the keys described in parameter-element.

Table2D element

In some cases, a table-element is not powerful enough to represent the relationship between the values of free parameters and other parameters, for example if the value of a parameter depends on two free parameters at once. This case is covered by a table2d element. A table2d-element allows to lookup the value of the result parameter for a row given by a rowindex and a column given by a colindex.

A table2d element is an associative array with the following keys:

• rowindex: mandatory, string: name of the parameter that is used to select a row. Has to be specified to be of type "Table Index" in the parameter-element. Note the restriction on the keys described in parameter-element.
• colindex: mandatory, string: name of the parameter that is used to select a column. Has to be specified to be of type "Table Index" in the parameter-element. Note the restriction on the keys described in parameter-element.
• columns: mandatory, list of strings. The possible values for the colindex.
• result: mandatory, string. The name of the parameter whose value is determined with this table.
• data: mandatory, associative array: The keys are possible values of the rowindex parameter, the values a list of values for the columns from which one is selected by the colindex.

Base file element

A base file element is an associative array containing information about a file. Depending on the type of the file the contained keys are different. However, there are some keys that are present in every base file element:

• filename: mandatory, string. The filename of the file
• author: mandatory, string or list of strings. The author of the file with e-mail address in <> or a list of several authors.
• license: mandatory, string. The license of the file. Must be one of the supported-licenses.
• type: mandatory, string. A string describing the type of the file.
• source: optional, string. A string describing the origin of the file.

Different data bases contain different base-file-types, for a list see list-of-base-file-types.