package amp.validator

Get desktop application:
View/edit binary Protocol Buffers messages

Specifies which AMP Layouts are supported by a given element. For the purpose of the validator, this specifies which values for layout, height, and width attributes are allowed. Also see https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md TODO(johannes): Make the error messages around layouts better. This may require revamping the documentation for elements and/or the above spec, so that a user gets more clearly informed about which layouts are applicable to a given tag, what happens when layout attribute or other attributes are not set, etc. NEXT AVAILABLE TAG: 4

Used in: TagSpec

• repeated AmpLayout.Layout supported_layouts = 1

  Specifies which layouts are supported by this element.

• optional bool defines_default_width = 2

  Specifies whether this element has default dimensions. This corresponds to being allowlisted in naturalDimensions_ in https://github.com/ampproject/amphtml/blob/main/src/static-layout.js.

• optional bool defines_default_height = 3

NEXT AVAILABLE TAG: 10

Used in: AmpLayout

• CONTAINER = 5

• FILL = 6

• FIXED = 2

• FIXED_HEIGHT = 3

• FLEX_ITEM = 7

• FLUID = 8

• INTRINSIC = 9

• NODISPLAY = 1

• RESPONSIVE = 4

• UNKNOWN = 0

An AncestorMarker is a state maintained on the stack of matching tags. When a TagSpec with an AncestorMarker matches, this Marker is placed on the stack until the matched html tag is popped from the stack. Other rules may be triggered by the presence of a specific AncestorMarker on the stack. NEXT AVAILABLE TAG: 2

Used in: AttrSpec, TagSpec

• repeated AncestorMarker.Marker marker = 1

NEXT AVAILABLE TAG: 2

Used in: AncestorMarker

• UNKNOWN = 0

• AUTOSCROLL = 1

  Set by <amp-sidebar> tags to allow autoscroll attributes on descendants. See https://github.com/ampproject/amphtml/pull/20524 for more context.

This spec is used by our CSS parser to determine what AT rules are allowed in the CSS spec. The term 'rule' here refers to the AT Rule in CSS, not a validation rule. NEXT AVAILABLE TAG: 4

Used in: CssSpec

• optional string name = 1

  Name of the AT rule to parse. Do not include the '@' symbol (e.g. '@media' should be encoded as 'media'.

• optional MediaQuerySpec media_query_spec = 3

  A MediaQuerySpec may only be set for an AtRuleSpec with the name "media". If not set, media queries will be left unparsed, so no errors or warnings about them will be reported.

Some tags share several attributes, so they're identified by unique key (see the attr_lists map in ValidatorRules). NEXT AVAILABLE TAG: 3

Used in: ValidatorRules

• optional string name = 1

• repeated AttrSpec attrs = 2

Attributes that are not covered by at least one of these specs are disallowed. Within a given context (e.g., for a given TagSpec), names are unique. NEXT AVAILABLE TAG: 29

Used in: AttrList, TagSpec

• repeated string enabled_by = 23

  If provided, the Type Identifier(s) that either enable or disable this AttrSpec. If a Type Identifier is in enabled_by then this AttrSpec will be used in validating parsed documents with that Type Identifier. If a Type Identifier is in disabled_by then this AttrSpec will not be used in validating parsed documents with that Type Identifier. An AttrSpec can not have both enabled_by and disabled_by set.

• repeated string disabled_by = 24

• optional string name = 1

  Use lower-case attribute names only.

• repeated string alternative_names = 2

• optional bool mandatory = 3

• optional string mandatory_oneof = 12

  Within the context of the tag, *exactly one* of the attributes tagged with this identifier must be present. Per convention, this identifier should list the tags participating in the mandatory oneof: e.g. mandatory_oneof: "['foo', 'bar']"

• optional string mandatory_anyof = 21

  Within the context of the tag, *at least one* of the attributes tagged with this identifier must be present. Per convention, this identifier should list the tags participating in the mandatory oneof: e.g. mandatory_oneof: "['foo', 'bar']"

• repeated string value = 4

  The attribute value must be equal to the value in this field.

  case sensitive

• repeated string value_casei = 18

  case insensitive

• optional string value_regex = 15

  case sensitive

• optional string value_regex_casei = 5

  case insensitive

• optional UrlSpec value_url = 14

• optional PropertySpecList value_properties = 11

  validates against a list of properties (see PropertySpec).

• optional bool value_doc_css = 27

  If set, the attribute value will be evaluated using the matching document level CSS rules. This flag is used for `style` attributes. If `value_doc_css` is set, only non-SVG css is applied. If `value_doc_css_svg` is set, SVG-specific CSS rules are also allowed for this attribute value.

• optional bool value_doc_svg_css = 28

  } end oneof

• optional AttrSpec.ValueSet add_value_to_set = 25

• optional AttrSpec.ValueSet value_oneof_set = 26

• optional AttrTriggerSpec trigger = 16

• optional string disallowed_value_regex = 6

  If set, then the attribute value may not match this regex, which is always applied case-insensitively and as a partial match.

• optional string deprecation = 7

  If set, generates a DEPRECATED_ATTR error with severity WARNING. The value of the deprecation field indicates what to use instead, e.g. the name of an attribute or tag.

• optional string deprecation_url = 8

  If provided, a URL which links to the AMP HTML spec for this deprecation.

• repeated CssDeclaration css_declaration = 20

  Valid CSS declarations.

• optional AttrSpec.DispatchKeyType dispatch_key = 13

  If set true, the TagSpec containing this AttrSpec will be evaluated first for any encountered tag which matches the tag name and this attribute spec. May only be set for an AttrSpec where mandatory=true and type matches those specified in the comments of DispatchKeyType above.

• optional bool implicit = 17

  If set to true, the TagSpec containing this AttrSpec implicitly has this attribute and the attribute is considered valid.

• repeated string requires_extension = 19

  If set, this attr is considered part of an amp extended component, and requires that the named extended component script tag is present on the page.

• optional AncestorMarker requires_ancestor = 22

  If set, this attr is invalid unless the current tag has an ancestor tag which set one or more of the required markers.

Used in: AttrSpec

• NONE_DISPATCH = 0

  Indicates that the attribute does not form a dispatch key.

• NAME_DISPATCH = 1

  Indicates that the name of the attribute alone forms a dispatch key.

• NAME_VALUE_DISPATCH = 2

  Indicates that the name + value of the attribute forms a dispatch key.

• NAME_VALUE_PARENT_DISPATCH = 3

  Indicates that the name + value + mandatory parent forms a dispatch key.

These two fields specify that values from one AttrSpec refer to values from another AttrSpec elsewhere on the page; validator will verify the references are not "dangling". These references may appear before or after their referents. For example, in the "id" AttrSpec in the "template" TagSpec, we have: add_value_to_set: TEMPLATE_IDS and in any "template" AttrSpec, we have: value_oneof_set: TEMPLATE_IDS NEXT AVAILABLE TAG: 3

Used in: AttrSpec, ValueSetProvision

• UNKNOWN_VALUESET = 0

  Never used

• TEMPLATE_IDS = 1

  <template id> values

• AMP_SCRIPT_IDS = 2

  <script id> values, referenced by <amp-script>

Used for validating attributes that require another attribute for some given set of conditions. E.g. attr name: "on" if_value_regex: "tap:.*" also_require_attr: "role" NEXT AVAILABLE TAG: 3

Used in: AttrSpec

• optional string if_value_regex = 1

  If set, attribute's value must match to also require attribute(s). If not set, attribute automatically also require attribute(s).

  case sensitive

• repeated string also_requires_attr = 2

  If set, other attributes - identified by their name string - must be present as well.

NEXT AVAILABLE TAG: 12

Used in: TagSpec

• optional int32 max_bytes = 1

  If set, the cdata contents cannot be greater than this length, in bytes. A value of -2 (default) indicates that there is no limit (unlimited). A value of -1 will always cause validation failure on match. -1 is used to implement the `amp-custom-length-check` attribute: (https://github.com/ampproject/amphtml/issues/22315#issuecomment-496681165)

• optional string max_bytes_spec_url = 2

  If provided, a URL which linking to a section / sentence in the AMP HTML spec.

• optional string mandatory_cdata = 3

  If non-empty, the text between the start / end tag must match this value.

• optional string cdata_regex = 6

  If non-empty, the text between the start / end tag must match this regex.

• optional CssSpec css_spec = 7

  If at least one CssSpec is provided, this cdata field will be parsed as CSS3, and any parsing errors will become validation errors.

• optional bool whitespace_only = 8

  If set to true, then only whitespace may be in the cdata contents. This is useful for script tags that reference extensions etc.

  } end oneof

• repeated DisallowedCDataRegex disallowed_cdata_regex = 4

  If any of these regexes match, then this cdata spec does not validate.

• optional bool doc_css_bytes = 11

  If true, the contents of this tag's CDATA text will be counted against the document level DocCssSpec CSS lengths.

TagSpec::child_tags uses this configuration to specify which child tags are expected for a specific tag. Matching child tags is done by tag name, while the parent is matched by TagSpec. The reason for this is that matching by tag spec name would produce less useful error messages, because we want to be able to produce a good message even if the tag spec name could not be determined because the enclosed child tag is invalid (no TagSpec matches). By doing a tag name match, we can produce a reasonable error regardless if a child tag was misplaced. NEXT AVAILABLE TAG: 5

Used in: TagSpec

• optional int32 mandatory_num_child_tags = 1

  Unless set to -1 (the default), the parent tag must have exactly |mandatory_num_child_tags| immediate child tags.

• repeated string first_child_tag_name_oneof = 2

  If at least one tag name is specified, then the first child of the parent tag must have one of the provided names.

• repeated string child_tag_name_oneof = 3

  If at least one tag name is specified, then the child tags of the parent tag must have one of the provided tag names.

• optional int32 mandatory_min_num_child_tags = 4

  Unless set to -1 (the default), the parent tag must have a minimum of |mandatory_min_num_child_tags| immediate child tags.

NEXT AVAILABLE TAG: 4

Used in: AttrSpec, DeclarationList, DocCssSpec

• optional string name = 1

  The name of the declaration (e.g. display). Use lower-case attribute names only.

• repeated string value_casei = 2

  This would be a oneof, but this file only uses features in protobuf 2.5.0. begin oneof { The valid values of the declaration (e.g. block).

• optional string value_regex_casei = 3

  } end oneof

NEXT AVAILABLE TAG: 10

Used in: CdataSpec

• repeated AtRuleSpec at_rule_spec = 1

  Spec for how to parse CSS AT rules, one per AT rule. Must not contain duplicate names, and must contain at least one entry for the default.

• optional bool validate_amp4ads = 5

  Enables checks specific to the draft A4A specification. TODO(powdercloud): Make this more generic.

• optional bool validate_keyframes = 6

  Enables checks specific to the style[keyframes] specification. TODO(chenshay): Make this more generic.

• repeated string declaration = 7

  Any declaration listed here are allowed.

• optional bool allow_important = 8

  If false, declarations tagged with `!important` are considered errors. Most AMP stylesheets disallow `!important` to reserve this override for AMP's own styles.

• optional SelectorSpec selector_spec = 9

Some style blocks share long lists of declarations, so they're identified by unique key. NEXT AVAILABLE TAG: 3

Used in: ValidatorRules

• optional string name = 1

• repeated CssDeclaration declaration = 2

A list of allowed tags for descendants of any level (children, grandchildren, great-grandchildren, etc). NEXT AVAILABLE TAG: 3

Used in: ValidatorRules

• optional string name = 1

• repeated string tag = 2

Regex which, if matches the cdata of a tag, causes the tag validation to fail. NEXT AVAILABLE TAG: 3

Used in: CdataSpec

• optional string regex = 1

  Syntax is partial match, use ^ and $ if you want global match.

• optional string error_message = 2

Exactly one DocCssSpec will match each AMP document. This spec defines the default css rules for style attributes and publisher style tags across the entire document. Rules for specific tags may be overridden by those tags. NEXT AVAILABLE TAG: 20

Used in: ValidatorRules

• repeated HtmlFormat.Code html_format = 1

  The html_format field tells the validator for which html formats (ie: (<html ⚡> vs <html a4⚡>) this DocCssSpec is defined for.

• repeated string enabled_by = 2

  If a Type Identifier is in enabled_by then this DocCssSpec will be used in validating parsed documents with that Type Identifier. If a Type Identifier is in disabled_by then this DocCssSpec will not be used in validating parsed documents;: with that Type Identifier. An DocCssSpec can not have both enabled_by and disabled_by set.

• repeated string disabled_by = 3

• optional string spec_url = 4

  If provided, a URL linking to a section / sentence in the AMP HTML spec.

• optional bool max_bytes_is_warning = 18

  Due to a bug, we allowed unlimited doc-level and per-inline-style bytes for CSS in non-AMP formats. To avoid breaking pages, some formats will only emit a warning for exceeding `max_bytes` and `max_bytes_per_inline_style`.

• optional int32 max_bytes = 5

  If set, the combined style amp-custom cdata contents and all inline style contents cannot be greater than this length, in bytes. A value of -2 (default) indicates that there is no limit (unlimited). A value of -1 will always cause validation failure.

• optional int32 max_bytes_per_inline_style = 6

  If set, the inline style content (per use) cannot be greater than this length, in bytes.

• optional bool url_bytes_included = 7

  If false, bytes inside URLs are not included in the byte calculation for `max_bytes`. This is used for handling signed exchange transformations which can potentially take the number of bytes over the 75,000 byte limit due to rewriting URLs to point at an AMP Cache.

• optional string max_bytes_spec_url = 8

  If provided, a URL linking to a section / sentence in the AMP HTML spec.

• optional bool allow_all_declaration_in_style = 10

  If true, all declarations are allowed in style tags and inline style attributes, regardless of the contents of the `declaration` list.

• optional bool expand_vendor_prefixes = 19

  If true, all variants of declarations that are vendor prefixes are allowed. for example, if `gradient` is an allowed declaration and this is true, then `-webkit-gradient` is also an allowed declaration.

• repeated CssDeclaration declaration = 11

  Any declaration listed here is allowed in custom style tags and style attributes in any tag.

• repeated CssDeclaration declaration_svg = 12

  In addition to those listed in 'declaration', any declaration listed here is allowed in style attributes for SVG elements.

• repeated string declaration_list = 13

  Top level lists of shared declarations, identified by unique key.

• repeated string declaration_list_svg = 14

  Top level lists of shared declarations, identified by unique key.

• optional UrlSpec image_url_spec = 15

  URLs found within CSS are checked against this spec.

• optional UrlSpec font_url_spec = 16

• optional bool allow_important = 17

  If false, declarations tagged with `!important` are considered errors. Most AMP stylesheets disallow `!important` to reserve this override for AMP's own styles.

Exactly one DocSpec will match each AMP document. This spec defines some default rules for the entire document scoped by it's HtmlFormat and any Type Identifiers. NEXT AVAILABLE TAG: 6

Used in: ValidatorRules

• repeated HtmlFormat.Code html_format = 1

  The html_format field tells the validator for which html formats (ie: (<html ⚡> vs <html a4⚡>) this DocSpec is defined for.

• repeated string enabled_by = 2

  If a Type Identifier is in enabled_by then this DocSpec will be used in validating parsed documents with that Type Identifier. If a Type Identifier is in disabled_by then this DocSpec will not be used in validating parsed documents with that Type Identifier. An DocSpec can not have both enabled_by and disabled_by set.

• repeated string disabled_by = 3

• optional int32 max_bytes = 4

  If set, the entire document's content cannot be greater than this length, in bytes. A value of -2 (default) indicates that there is no limit (unlimited).

• optional string max_bytes_spec_url = 5

  If provided, a URL linking to a section / sentence in the AMP HTML spec.

This feature was removed in October 2019, however there are still some callers that expect an ErrorCategory to be set. Do not rely on this in new code. TODO(#25188): Remove ErrorCategory completely.

(message has no fields)

Used in: ValidationError

• UNKNOWN = 0

NEXT AVAILABLE TAG: 3

Used in: ValidatorRules

• optional ValidationError.Code code = 1

• optional string format = 2

Used in the verbose validator to select between multiple generated error types for a failing error. A higher number means that the error is more specific, ie: more helpful, preferred. NEXT AVAILABLE TAG: 3

Used in: ValidatorRules

• optional ValidationError.Code code = 1

• optional int32 specificity = 2

Specs specific to AMP Extensions. This is a field within TagSpec that replaces the standard tagspec list of attributes, requirements, etc. NEXT AVAILABLE TAG: 11

Used in: TagSpec

• optional string name = 1

  e.g. "amp-video". This is used both as the attribute value for the 'custom-element' attribute value as well as part of the 'src' attribute value.

• repeated string version = 2

  e.g. "0.1", "1.0", "latest".

• optional string version_name = 9

  If multiple TagSpecs for the same extension exist, separated by version, specify a version_name string to disambiguate their spec_names. For example, "v1.0" or "v0.1-0.2". This string will become part of the name used for referring to this extension in validator error messages.

• repeated string deprecated_version = 3

  deprecated_version must be a strict subset of version. If the version matches a deprecated_version, validation will emit a warning.

• repeated string bento_supported_version = 10

  Bento supported versions (e.g. "1.0").

• optional ExtensionSpec.ExtensionType extension_type = 8

• optional bool deprecated_allow_duplicates = 6

  For older tags, we did not originally require that the tag only be included once, so those tags are exempted from the multiple inclusion ban.

• optional ExtensionSpec.ExtensionUsageRequirement requires_usage = 7

Most extensions are custom-elements. For custom-template extensions, this value needs to be set true. E.g: amp-mustache. NEXT AVAILABLE TAG: 4

Used in: ExtensionSpec

• UNKNOWN = 0

• CUSTOM_ELEMENT = 1

• CUSTOM_TEMPLATE = 2

• HOST_SERVICE = 3

TagSpec.requires_extension will be set to the new extension's name on one or more TagSpecs that require that extension. This typically creates 2 validation requirements: 1) If a tag is on the page whose TagSpec has the requires_extension field set, but that extension is not present, this is an error. (Usage requires extension). 2) If an extension is on the page, but no tags indicating usage of that extension via the required_extension field are on the page, this is an error. (Extension requires usage). The second requirement (extension requires usage) has a few exceptions: 1) For older extensions, implemented before these tagspec rules, we do not want to introduce a breaking change, so we exempt these extensions from the usage requirement. New extensions must use ERROR. 2) Some extensions, such as `amp-dynamic-css-classes`, do not have any associated tag in the document indicating usage. These extensions do not trigger warnings or errors. NEXT AVAILABLE TAG: 4

Used in: ExtensionSpec

• ERROR = 1

• EXEMPTED = 2

  Exception for exempted extensions. #1 above.

• NONE = 3

  Exception for extensions with no usage-indicating tag. #2 above.

The HtmlFormat is the declared format in the top-level html tag, which prescribes a particular set of validation rules. This should be kept in sync with Request.HtmlFormat in github.com/ampproject/amppackager/transformer/request/request.proto.

(message has no fields)

NEXT AVAILABLE TAG: 6

Used in: DocCssSpec, DocSpec, TagSpec

• UNKNOWN_CODE = 0

  Never used

• AMP = 1

• AMP4ADS = 2

• AMP4EMAIL = 3

• EXPERIMENTAL = 4

  Currently unused

This spec is used when parsing a media query inside a CSS @media rule. NEXT AVAILABLE TAG: 5

Used in: AtRuleSpec

• optional bool issues_as_error = 1

  If issues_as_error is true, then parsing errors and invalid types / features will be treated as validator errors, otherwise warnings.

• repeated string type = 2

  These are the media query types and features allowed within the stylesheet. http://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Syntax

• repeated string feature = 3

Used for validating properties in attribute values. Our validator (via parse-viewport.h) implements the parsing algorithm as described here: https://drafts.csswg.org/css-device-adapt/#parsing-algorithm NEXT AVAILABLE TAG: 5

Used in: PropertySpecList

• optional string name = 1

  Must be lowercase, and will be matched case-insensitively.

• optional bool mandatory = 2

• optional string value = 3

  Must be lowercase, and will be matched case-insensitively.

• optional double value_double = 4

  } end oneof

NEXT AVAILABLE TAG: 2

Used in: AttrSpec

• repeated PropertySpec properties = 1

TagSpecs and reference points. Any TagSpec may define a list of reference points via the TagSpec::reference_points field. These reference points specify how DOM elements that are children of this parent tag fulfill particular functionality. For instance, a widget (implemented as an AMP tag) may require a login reference point. Any valid AMP tag would be allowed, whether it's a clickable DIV or an AMP-IMG or a BUTTON, so long as it *also* conforms to the reference point specification. This specification is a TagSpec which does not define a name (the name is set to the special value '$REFERENCE_POINT'), but rather identifies the reference point with AttrSpec requirements. For instance, the login reference point may require that there be a login attribute, or some end-point attribute with a URL, or similar. Therefore, for any child tags of a tag that defines reference points, they are first matched against these reference points, and only then are they validated as regular tags against the TagSpecs that are not reference points while their reference point attributes are skipped. The complexity of this mechanism is unfortunate but reduces the markup required and makes CSS styling more convenient. Please see the amp-live-list specification for an example. NEXT AVAILABLE TAG: 4

Used in: TagSpec

• optional string tag_spec_name = 1

  A tag spec identified by its TagSpec::spec_name which specifies how a specific functionality for the parent tag is assigned.

• optional bool mandatory = 2

  At least one of the child tags of the parent defining this reference point must match it.

• optional bool unique = 3

  At most one of the child tags of the parent defining this reference point must match it.

This spec is used when parsing a CSS selector group as the prelude of a CSS qualified rule. For example "div.foo span.bar". If no SelectorSpec is provided, the selector groups are unconstrained. NEXT AVAILABLE TAG: 4

For each SelectorSpec list provided a single list element value of "*" indicates that any value is allowed (ie: that feature is unconstrained). An empty list indicates that no value is allowed (ie: that feature is disallowed). Otherwise, the list values are the only allowed values.

Used in: CssSpec

• repeated string attribute_name = 1

  Allowed attribute selector names. For example `foo` in the selector `.a[foo=bar]`.

• repeated string pseudo_class = 2

  Allowed pseudo class names. For example `checked` in `.a:checked`.

• repeated string pseudo_element = 3

  Allowed pseudo element names. For example `before` in `.a::before`.

Tags that are not covered by at least one of these specs are disallowed. Some tags are mandatory. Note that the tag name is not unique, that is, there can be multiple tag specs covering the same name, e.g., for multiple meta tags (with different attributes). NEXT AVAILABLE TAG: 40

Used in: ValidatorRules

• repeated HtmlFormat.Code html_format = 21

  The html_format field tells the validator for which html formats (ie: (<html ⚡> vs <html a4⚡>) this HTML TagSpec is allowed to validate. The repeated field is not allowed to be empty, it must have at least one HtmlFormat.

• repeated string enabled_by = 35

  If provided, the Type Identifier(s) that either enable or disable this TagSpec. If a Type Identifier is in `enabled_by` then this TagSpec will be used in validating parsed documents which include that Type Identifier. If a Type Identifier is in `disabled_by` then this TagSpec will not be used in validating parsed documents which include that Type Identifier. A TagSpec can not have both `enabled_by` and `disabled_by` set.

• repeated string disabled_by = 36

• optional string tag_name = 1

  Use UPPER-CASE tag names only. If adding the same tag twice, then they must also have a spec_name string which is unique throughout all detail. Note: "$REFERENCE_POINT" is a special tag_name value. Reference points are partial tag specs which don't have a defined tag_name.

• optional string spec_name = 2

  If provided, the spec_name must be unique within the validator rules. This string forms a a unique id for this TagSpec. If not set, the tag_name field is used as the unique id. This string is not used in error messages, see descriptive_name for that.

• optional string descriptive_name = 39

  If `tag_name` is not a sufficient descriptor for error messages having to do with this tag spec, provide a `descriptive_name` value, which if present will be used in place of `tag_name`. Typically `descriptive_name` should include the tag_name in it, and should avoid using < and > in case downstream libraries of the validator fail to properly HTML escape rendered error strings.

• optional TagSpec.NamedId named_id = 33

• optional ExtensionSpec extension_spec = 27

  If provided, this is a SCRIPT tag defining an amp custom element extension. The other fields, such as expected attributes, will be validated by the extension spec rules.

• repeated string requires_extension = 28

  If set, this tag is considered part of an amp extended component, and requires that the named extended component script tag is present on the page.

• optional bool mandatory = 3

  If true, a tag conforming to this tag spec must occur at least once within the document.

• optional string mandatory_alternatives = 4

  A string identifying that this tag belongs to a set of alternative choices from which at least one needs to be satisfied.

• optional bool unique = 5

  If true, a tag conforming to this tag spec may occur at most once within the document.

• optional bool unique_warning = 25

  If true, a tag conforming to this tag spec should occur at most once within the document. That is, unlike for unique, we'll emit a warning.

• optional string mandatory_parent = 6

  If set to "$ROOT", this tag must be the root tag. If set to any other string, the tag must be the direct child of the specified mandatory parent tag.

• optional string mandatory_ancestor = 15

  If set, the tag must descend from (not necessarily direct parent of) the specified mandatory parent string which is either a tag name or a tag spec_name (e.g. tag.name = "!DOCTYPE" or tag.spec_name = "html doctype").

• optional string mandatory_ancestor_suggested_alternative = 16

  Use only for tags where mandatory_ancestor is set. If tag validation fails due to the mandatory_ancestor, and this field is set, then the error detail will suggest the tag specified here as an alternative to consider.

• repeated string disallowed_ancestor = 13

  This tag may not descend from any tag with any of these tag names or tag spec_names (e.g. tag.name = "!DOCTYPE" or tag.spec_name = "html doctype").

• optional string descendant_tag_list = 29

  If set, all of the tag's descendants must be tags from the named list. A tag not in the named list will generate an error.

• repeated string also_requires_tag_warning = 22

  If set, other tags - identified by their detail string - must be present as well or a warning will be issued (will not invalidate doc).

• repeated string satisfies_condition = 23

  Expresses a generic condition which is satisfied if this tag is found. Used in combination with the `requires` attribute on a different tag.

• repeated string requires_condition = 24

  Expresses a generic condition which must be satisfied if this tag is found. Used in combination with the `satisfies` attributes on a different tag.

• repeated string excludes_condition = 32

  The excludes field is a generic condition, which must not be satisfied if this tag is found. Otherwise a TAG_EXCLUDED_BY_TAG error will be generated. Used in combination with the `satisfies` attributes on a different tag.

• optional string deprecation = 17

  If set, generates a DEPRECATED_TAG error with severity WARNING. The value of the deprecation field indicates what to use instead, e.g. the name of a tag.

• optional string deprecation_url = 18

  If provided, a URL which links to the AMP HTML spec for this deprecation.

• optional bool explicit_attrs_only = 34

  This TagSpec will only validate against attributes explicitly listed within the TagSpec (attrs and attr_lists). No attributes from $GLOBAL_ATTRS and $AMP_LAYOUT_ATTRS are valid unless explicitly added as an attribute within the TagSpec. The field `amp_layout` is not allowed to be set when `explicit_attrs_only` is true.

• repeated AttrSpec attrs = 7

  Attribute specifications related to this tag.

• repeated string attr_lists = 8

  Top level attr lists of shared tags, identified by unique key (see attr_lists map in ValidatorRules).

• optional CdataSpec cdata = 12

  Note that these are evaluated after a particular TagSpec has been evaluated. Unlike other checks in this TagSpec, we no longer have the ability to fall back on a different TagSpec.

• optional ChildTagSpec child_tags = 19

  Specifies which tags can be the child tags, that is, immediately children of this tag in the document.

• optional bool siblings_disallowed = 30

  If set to true, this tag cannot have any siblings.

• optional bool mandatory_last_child = 31

  If set to true, this tag must be the last child of its parent.

• repeated ReferencePoint reference_points = 20

  The reference_points defined by this TagSpec instance determine how specific child tags are identified. Please see the comment for the ReferencePoint message.

• optional string spec_url = 10

  If provided, a URL which linking to a section / sentence in the AMP HTML spec. If a TagSpec contains a requires_extension field, spec_url will be inherited from the named extension, unless overridden by the setting it here.

• optional AmpLayout amp_layout = 11

  If set, specifies which AMP Layouts are supported by this element.

• optional AncestorMarker mark_descendants = 38

  If set, triggers related validation rules for descendants of this tag.

NamedId's are used to uniquely identify specific TagSpecs in the validator rules in a stable manner. Most TagSpecs have no set NamedId. If a TagSpec has a NamedId it must be unique. In other words, no two TagSpec's may have the same NamedId except for the NOT_SET (0) value. NEXT AVAILABLE TAG: 3

Used in: TagSpec

• NOT_SET = 0

• LINK_FONT_STYLESHEET = 1

  By convention, the first "word" in the Id should be the tag_name.

• STYLE_AMP_CUSTOM = 2

Used for validating urls in attribute values (such as href/src/srcset). NEXT AVAILABLE TAG: 5

Used in: AttrSpec, DocCssSpec

• repeated string protocol = 1

  protocol must be in lowercase (e.g. "javascript" not "JavaScript").

• optional bool allow_relative = 2

• optional bool allow_empty = 3

  Whether the empty string '' is allowed for this URL value.

We record validation errors in a structured form, so that they can be worked with in code - e.g., to provide translated messages. In the Javascript implementation (validator.js), you may find the amp.validator.renderErrorMessage function which will make a human-readable string from the structured form. It should be easy to port this to other languages as needed; for instance Google has implementations in C++, Java, and for templates used in some frontends. NEXT AVAILABLE TAG: 10

Used in: ValidationResult, ValueSetRequirement

• optional ValidationError.Severity severity = 6

• optional ValidationError.Code code = 1

• optional int32 line = 2

• optional int32 col = 3

• optional string spec_url = 5

• repeated string params = 7

• optional ErrorCategory.Code category = 8

  This field is deprecated. Do not use.

• optional string data_amp_report_test_value = 9

  Used only in JavaScript, if an error is emitted for a specific HTML tag and if that HTML tag has an attribute named data-amp-report-test, this string will be set and contain the value found for that attribute. This is used in tests to match specific errors to specific tags in the test cases. It is not a rendered value.

NEXT AVAILABLE TAG: 124

Used in: ErrorFormat, ErrorSpecificity, ValidationError

• UNKNOWN_CODE = 0

• INVALID_DOCTYPE_HTML = 111

• MANDATORY_TAG_MISSING = 1

• TAG_REQUIRED_BY_MISSING = 24

• WARNING_TAG_REQUIRED_BY_MISSING = 76

• TAG_EXCLUDED_BY_TAG = 101

• WARNING_EXTENSION_UNUSED = 79

• EXTENSION_UNUSED = 84

• WARNING_EXTENSION_DEPRECATED_VERSION = 80

• INVALID_EXTENSION_VERSION = 122

• INVALID_EXTENSION_PATH = 123

• NON_LTS_SCRIPT_AFTER_LTS = 112

• LTS_SCRIPT_AFTER_NON_LTS = 113

• INCORRECT_SCRIPT_RELEASE_VERSION = 119

• DISALLOWED_AMP_DOMAIN = 121

• ATTR_REQUIRED_BUT_MISSING = 61

• DISALLOWED_TAG = 2

• GENERAL_DISALLOWED_TAG = 51

• DISALLOWED_SCRIPT_TAG = 88

• DISALLOWED_ATTR = 3

• DISALLOWED_STYLE_ATTR = 81

• INVALID_ATTR_VALUE = 4

• DUPLICATE_ATTRIBUTE = 94

• ATTR_VALUE_REQUIRED_BY_LAYOUT = 27

• MISSING_LAYOUT_ATTRIBUTES = 105

• IMPLIED_LAYOUT_INVALID = 22

• SPECIFIED_LAYOUT_INVALID = 26

• MANDATORY_ATTR_MISSING = 5

• MANDATORY_ONEOF_ATTR_MISSING = 28

• MANDATORY_ANYOF_ATTR_MISSING = 104

• DUPLICATE_DIMENSION = 60

• DUPLICATE_UNIQUE_TAG = 6

• DUPLICATE_UNIQUE_TAG_WARNING = 77

• WRONG_PARENT_TAG = 7

• STYLESHEET_TOO_LONG = 50

• STYLESHEET_AND_INLINE_STYLE_TOO_LONG = 102

• INLINE_STYLE_TOO_LONG = 103

• INLINE_SCRIPT_TOO_LONG = 118

• MANDATORY_CDATA_MISSING_OR_INCORRECT = 9

• CDATA_VIOLATES_DENYLIST = 30

• NON_WHITESPACE_CDATA_ENCOUNTERED = 82

• INVALID_JSON_CDATA = 106

• DEPRECATED_ATTR = 11

• DEPRECATED_TAG = 12

• MANDATORY_PROPERTY_MISSING_FROM_ATTR_VALUE = 14

• INVALID_PROPERTY_VALUE_IN_ATTR_VALUE = 15

• MISSING_URL = 35

• INVALID_URL = 36

• INVALID_URL_PROTOCOL = 37

• DISALLOWED_DOMAIN = 62

• DISALLOWED_RELATIVE_URL = 49

• DISALLOWED_PROPERTY_IN_ATTR_VALUE = 16

• MUTUALLY_EXCLUSIVE_ATTRS = 17

• UNESCAPED_TEMPLATE_IN_ATTR_VALUE = 18

• TEMPLATE_PARTIAL_IN_ATTR_VALUE = 19

• TEMPLATE_IN_ATTR_NAME = 20

• INCONSISTENT_UNITS_FOR_WIDTH_AND_HEIGHT = 21

• DISALLOWED_TAG_ANCESTOR = 23

• MANDATORY_LAST_CHILD_TAG = 89

• MANDATORY_TAG_ANCESTOR = 31

• MANDATORY_TAG_ANCESTOR_WITH_HINT = 32

• ATTR_DISALLOWED_BY_IMPLIED_LAYOUT = 33

• ATTR_DISALLOWED_BY_SPECIFIED_LAYOUT = 34

• INCORRECT_NUM_CHILD_TAGS = 56

• INCORRECT_MIN_NUM_CHILD_TAGS = 85

• DISALLOWED_CHILD_TAG_NAME = 57

• DISALLOWED_FIRST_CHILD_TAG_NAME = 58

• DISALLOWED_MANUFACTURED_BODY = 64

• CHILD_TAG_DOES_NOT_SATISFY_REFERENCE_POINT = 66

• MANDATORY_REFERENCE_POINT_MISSING = 67

• DUPLICATE_REFERENCE_POINT = 68

• TAG_NOT_ALLOWED_TO_HAVE_SIBLINGS = 87

• TAG_REFERENCE_POINT_CONFLICT = 69

• CHILD_TAG_DOES_NOT_SATISFY_REFERENCE_POINT_SINGULAR = 70

• BASE_TAG_MUST_PRECEED_ALL_URLS = 78

  TODO(gregable): Fix this spelling error: 'precede'

• MISSING_REQUIRED_EXTENSION = 83

• ATTR_MISSING_REQUIRED_EXTENSION = 97

• DOCUMENT_TOO_COMPLEX = 86

• INVALID_UTF8 = 96

• DOCUMENT_SIZE_LIMIT_EXCEEDED = 108

• DEV_MODE_ONLY = 109

• AMP_EMAIL_MISSING_STRICT_CSS_ATTR = 120

• VALUE_SET_MISMATCH = 110

• CSS_SYNTAX_INVALID_AT_RULE = 29

• CSS_SYNTAX_STRAY_TRAILING_BACKSLASH = 38

• CSS_SYNTAX_UNTERMINATED_COMMENT = 39

• CSS_SYNTAX_UNTERMINATED_STRING = 40

• CSS_SYNTAX_BAD_URL = 41

• CSS_SYNTAX_EOF_IN_PRELUDE_OF_QUALIFIED_RULE = 42

• CSS_SYNTAX_INVALID_DECLARATION = 43

• CSS_SYNTAX_INCOMPLETE_DECLARATION = 44

• CSS_SYNTAX_ERROR_IN_PSEUDO_SELECTOR = 45

• CSS_SYNTAX_MISSING_SELECTOR = 46

• CSS_SYNTAX_NOT_A_SELECTOR_START = 47

• CSS_SYNTAX_UNPARSED_INPUT_REMAINS_IN_SELECTOR = 48

• CSS_SYNTAX_MISSING_URL = 52

• CSS_SYNTAX_INVALID_URL = 53

• CSS_SYNTAX_INVALID_URL_PROTOCOL = 54

• CSS_SYNTAX_DISALLOWED_DOMAIN = 63

• CSS_SYNTAX_DISALLOWED_RELATIVE_URL = 55

• CSS_SYNTAX_INVALID_ATTR_SELECTOR = 59

• CSS_SYNTAX_INVALID_PROPERTY = 90

• CSS_SYNTAX_INVALID_PROPERTY_NOLIST = 95

• CSS_SYNTAX_QUALIFIED_RULE_HAS_NO_DECLARATIONS = 91

• CSS_SYNTAX_DISALLOWED_QUALIFIED_RULE_MUST_BE_INSIDE_KEYFRAME = 92

• CSS_SYNTAX_DISALLOWED_KEYFRAME_INSIDE_KEYFRAME = 93

• CSS_SYNTAX_MALFORMED_MEDIA_QUERY = 98

• CSS_SYNTAX_DISALLOWED_MEDIA_TYPE = 99

• CSS_SYNTAX_DISALLOWED_MEDIA_FEATURE = 100

• CSS_SYNTAX_DISALLOWED_ATTR_SELECTOR = 114

• CSS_SYNTAX_DISALLOWED_PSEUDO_CLASS = 115

• CSS_SYNTAX_DISALLOWED_PSEUDO_ELEMENT = 116

• CSS_SYNTAX_DISALLOWED_PROPERTY_VALUE = 71

• CSS_SYNTAX_DISALLOWED_IMPORTANT = 117

• CSS_EXCESSIVELY_NESTED = 107

• CSS_SYNTAX_DISALLOWED_PROPERTY_VALUE_WITH_HINT = 72

  The following codes are currently used only by A4A CSS validation.

• CSS_SYNTAX_PROPERTY_DISALLOWED_WITHIN_AT_RULE = 73

• CSS_SYNTAX_PROPERTY_DISALLOWED_TOGETHER_WITH = 74

• CSS_SYNTAX_PROPERTY_REQUIRES_QUALIFICATION = 75

NEXT AVAILABLE TAG: 5

Used in: ValidationError

• UNKNOWN_SEVERITY = 0

• ERROR = 1

  A document with at least one error of this severity fails validation.

• WARNING = 4

  A document may have warnings and still pass validation.

  DO NOT REASSIGN the previously used values 2, 3.

The validation result provided by Validator instances (see Validator::Result in validator.h). To render such a proto see RenderValidationResult. NEXT AVAILABLE TAG: 9

• optional ValidationResult.Status status = 2

• repeated ValidationError errors = 1

• optional int32 validator_revision = 3

  The following field is deprecated and can return any value. Do not depend on this.

• optional int32 spec_file_revision = 4

• optional int32 transformer_version = 6

  If the AMP document is a transformed AMP document, then this is the version of the transformers that were used to transform it. If the document is not transformed, then the transformer_version's value will be 0. Note: the AMP Pacakager's transformer library specifies the version as int64. However, JavaScript does not natively support int64 so int32 is used instead. https://github.com/ampproject/amppackager/blob/master/transformer/transformers/context.go

• repeated string type_identifier = 5

  The type idenfitier of the parsed document, e.g. AMP, AMP4ADS or some other type that has yet to be defined. These are declared on the HTML tag and parsed by the Validator Engine.

• repeated ValueSetProvision value_set_provisions = 7

  The set of provisions from all matching AttrSpecs in this TagSpec match. If the TagSpec is selected, these will be added to the final set of provisions.

• repeated ValueSetRequirement value_set_requirements = 8

  The set of requirements from all matching AttrSpecs in this TagSpec match. If the TagSpec is selected, these will be added to the final set of requirements.

NEXT AVAILABLE TAG: 3

Used in: ValidationResult

• UNKNOWN = 0

• PASS = 1

• FAIL = 2

Top level message - start reading here. The validator knows about a set of tag specifications. NEXT AVAILABLE TAG: 22

• repeated TagSpec tags = 1

• repeated AttrList attr_lists = 7

• optional int32 min_validator_revision_required = 4

  The min file revision for validator.cc which can digest this file.

• optional int32 spec_file_revision = 6

  See comment in validator.protoascii.

• optional string template_spec_url = 8

  Spec URL for information about mustache templates.

• optional string styles_spec_url = 15

  Spec URL for information about styles and amp-custom stylesheet

• optional string script_spec_url = 17

  Spec URL for information about script tags.

• repeated ErrorFormat error_formats = 9

• repeated ErrorSpecificity error_specificity = 13

• repeated DescendantTagList descendant_tag_list = 16

• repeated DocSpec doc = 21

  The DocSpec rules are scoped by the document's HtmlFormat and Type Identifiers and defined within each DocSpec.

• repeated DocCssSpec css = 19

• repeated DeclarationList declaration_list = 20

A value to be added to a particular ValueSet, as found when scanning the document (i.e. AttrSpec.add_value_to_set). NEXT AVAILABLE TAG: 3

Used in: ValidationResult, ValueSetRequirement

• optional AttrSpec.ValueSet set = 1

  The collection to add the attribute value to.

• optional string value = 2

  The value of the attribute itself.

A requirement that a particular value appears in a particular ValueSet (i.e. AttrSpec.value_oneof_set). All the provisions and requirements are collected until the document has been fully scanned, and then compared to ensure that all requirements are met. This allows provisions to appear after (or even alongside) requirements. NEXT AVAILABLE TAG: 3

Used in: ValidationResult

• optional ValueSetProvision provision = 1

  The provision that is required.

• optional ValidationError error_if_unsatisfied = 2

  The error that will appear if the requirement is not met. This includes the line/col of the attribute that makes the requirement.