[How to Read the Spec] How to Learn HTML Elements

The <search> element has been added to the HTML Standard. Since it is a new element for me too, I would like to take this opportunity to share how I research and learn when I encounter a new element. This can be applied not only to new elements but also to investigating existing ones. I believe it will be helpful for beginners as well as those who make a living out of markup.

Investigating the background of adding new elements

This part is only for those who are interested. If you only want to know the facts, feel free to skip it, as it might be a source of confusion.

It's a good idea to start with the Pull Requests (PRs) on the HTML Standard GitHub repository. Discussions and updates happen on GitHub. For example, the <search> element was updated via PR #7320: Add the <search> element.

To keep up with updates in the first place, you can check closed PRs sorted by update date, or follow @htmlstandard on Twitter, which tweets only about updates. In my case, I often check Twitter. That's how I learned about the addition of <search>.

https://twitter.com/htmlstandard/status/1639083303117651968

The link in the tweet takes you to the diff page rather than the main PR page. To navigate to the main PR from there, click on the linked PR number in the section where the branch and PR number are listed.

From there, check the contents of the PR, related Issues, related PRs, and the original proposal. Since these things usually start with a proposal, it's common for there to be discrepancies between the initial proposal and the final specification. It might be less confusing to check the final results first.

Checking the page where element specifications are listed

Let's look at the element specifications. First, to find the right page, the table of contents page is a good place to look. Lists of elements and attributes are provided in tables. Use your browser's find-in-page feature to search for the element. Since we are looking for <search>, we'll search for search in the Elements table.

At this point, we can already see an overview like "Container for search controls," content categories being "flow content" and "palpable content," the expected parent/child categories being "flow content," allowed attributes being only global attributes, and the IDL interface being HTMLElement. Reading this summary alone is useful. For some, this might be enough. However, updates are often missed in this table (leading to PRs for corrections), so for a thorough investigation, don't take it at face value and check the actual specification page. This table is also non-normative (non-normative).

The header cell at the start of the row is a link, so follow it to the element's specification page. The <search> element is explained in section “4.4.15 The search element”. You don't need to worry about the section number; it's just for classification and changes when elements are added or removed^[1].

Checking the properties of the element

The properties of the element are listed. These properties are very important; think of them as defining the "lexical rules" and "vocabulary rules" out of the "lexical," "vocabulary," and "semantic" rules^[2] for checking HTML specifications.

Categories

This indicates which content categories the element itself belongs to within the content model. We can see that <search> belongs to "flow content" and "palpable content."

To be honest, you don't need to worry too much about this. Since you'll look at lists far more often for content categories, please don't think "I must memorize this...!" There's no need to memorize it. What's more important are the next two sections.

Contexts in which this element can be used

This translates to "In what context can it be used?" In other words, what is allowed as a "parent" or "ancestor." In the case of <search>, it says "Where flow content is expected," so the "parent element = flow content" is required.

It's perfectly fine to look up the parent element's content category only at this point.

Content model

This indicates the content categories permitted as content. In other words, what is allowed as a "child" or "descendant." In the case of <search>, it allows "flow content."

For <search>, it's very simple, but for example, <div> is complex (try scrolling to the next element on the same page).

Content model:

If the element is a child of a dl element: one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.
If the element is not a child of a dl element: flow content.

In summary, it requires one of the following to be met:

• If <div> is a child element of something other than <dl>, flow content is allowed for child elements.
• If <div> is a child element of <dl>, it must be one or more <dt> followed by one or more <dd> (and script-supporting elements may be mixed in between).

You might think, "Wait, wait, wait... what...?" Content model definitions can have such complex cases. Conditions regarding what the parent element is may be attached, or requirements for child elements may specify particular elements or limits on the number (like "one or more" in the example) instead of just content categories. Consider simple cases to be the exception.

You can see that understanding only the content category of the element itself does not mean you understand the nesting relationships of the element. It is necessary to grasp it as a single "nesting rule," including the rules for parents/ancestors and the rules for children/descendants.

Tag omission in text/html

This specifies whether tags can be omitted. For <search>, it says "Neither tag is omissible," so "neither" can be omitted. "Neither" refers to the "start tag" and the "end tag." While many people know about the omission of the "end tag," it is written this way because there are actually elements where the "start tag" can be omitted as well.

"In text/html" also means strictly "in HTML syntax." This implies it may not be the case in XML, XHTML, SVG, or other places that differ strictly from HTML. Well, you'll rarely encounter such cases, though.

Content attributes

This defines the attributes that the element itself can have. For <search>, it is only global attributes. Depending on the element, element-specific attributes are listed here. Explanations for each element-specific attribute follow after the explanation of the element itself.

Accessibility considerations

These are the accessibility-related regulations, which in essence are the WAI-ARIA regulations. "For authors" provides information for those writing HTML and links to ARIA in HTML. On the other hand, "For implementers" provides information for UA (browser) implementers and links to HTML AAM (HTML Accessibility API Mappings).

Since you are likely someone involved in web production or UI development writing HTML, check the "For authors" section in ARIA in HTML.

It specifies the implicit semantics (Implicit ARIA semantics) (which can be rephrased as the "implicit role"), the roles allowed for overriding, and the ARIA states and properties.

For <search>, the implicit role is search, and overriding with roles like form, group, none, presentation, and region is permitted. The provision "Global aria-* attributes and any aria-* attributes applicable to the allowed roles" indicates that global ARIA states and properties are allowed, plus any specific ARIA states and properties defined for the role currently in use.

These "specific ARIA states and properties defined for the role" change depending on which role the element is currently set to. Since <search> has an implicit role of search, it allows the ARIA states and properties defined for the search role by default. however, if you use <search role="form">, it only allows those defined for the form role. Because it varies by role, be careful not to directly link "element = allowed ARIA states."

DOM interface

This is the regulation to understand when performing DOM operations with JavaScript. For <search>, it is defined as HTMLElement, which means that at this stage, it does not have any special properties or methods. When an element has a specific interface, it is often named something like HTMLSearchElement. In such cases, explanations for each specific property and method follow after the element's description.

---

Now, as mentioned at the beginning of the chapter, the properties covered so far are the "lexical rules" and "vocabulary rules." There is no room for interpretation here. They are completely fixed rules. They are not ambiguous regulations like "it might be this" or "there is a possibility of that." This means they can be checked mechanically. In other words, you don't need to memorize them. Whether your HTML follows these regulations can be solved by relying on tools such as Nu Html Checker, axe DevTools - Web Accessibility Testing, axe Accessibility Linter, and Markuplint. I'll say it again: you don't need to memorize them. Just use the tools.

Deciphering semantic rules

Now, this is where the real work begins. From here on, ambiguity and room for interpretation come into play.

• Body text explanation
• Notes
• Examples

Since several of these are often included, let's decipher them while looking at each one. While you need to understand the body text as the foundation and the notes as mere supplements, it's important to be careful because important information is sometimes included in the notes. Also, since notes sometimes set the stage for code examples, you should assume there is almost nothing you can skip reading.

Links are sometimes provided for terms in the body text or notes. These serve as clues for deciphering, and to avoid interpreting based solely on the wording, you should properly read the explanation of the linked terms and the context in which they are used to reduce misunderstandings.

Furthermore, this explanation section may be updated. New elements or attributes, in particular, will be updated frequently. Recently, elements related to <dialog> and the Popover API have been updated often. Additional precautions regarding accessibility may also be included. I recommend checking them periodically (or monitoring PRs). <search> will likely undergo repeated updates over the months and years, just like the others.

As for the English, I think it's fine to use translation tools like DeepL or GPT to decipher it. For beginners, it might make your head spin with all the technical jargon, but you'll get used to it. If you build up your training by reading repeatedly, you'll start to understand bit by bit.

Since these semantic rules rely heavily on the reader's interpretation, I recommend discussing them as much as possible with others who make a living out of markup or with experts. It might be interesting to start an interpretation thread in your own organization or community. I love such discussions myself, so please invite me if you have the chance. This is one of the best parts of HTML.

脚注

1. In this case, the addition of <search> moved <div> from 4.4.15 to 4.4.16. That's just how it goes.

2. From the book HTML Kaitai Shinsho (HTML Deconstruction Guide). Refer to P14 "02 HTML Specifications - Rules for Content Creators."