Semantics and Structure of Name-Value Pairs

Question

This is a question I have been struggling with for a while. What is the proper way to mark up name/value pairs?

I'm fond of the <dl> element, but it presents a problem: There is no way to separate one pair from another - they have no unique container. Visually, the code lacks definition. Semantically, though, I think this is the correct markup.

<dl>
    <dt>Name</dt>
    <dd>Value</dd>
    <dt>Name</dt>
    <dd>Value</dd>
</dl>

In the above code, it is difficult to properly offset the pairs visually, both in code and rendered. If I wanted to, for instance, but a border around each pair, that would be a problem.

We may point to tables. It could be argued that name-value pairs are tabular data. That seems incorrect to me, but I see the argument. However, the HTML does not differentiate the name from the value, except in position, or with the addition of class names.

<table>
    <tr>
        <td>Name</td>
        <td>Value</td>
    </tr>
    <tr>
        <td>Name</td>
        <td>Value</td>
    </tr>
</table>

This makes much more sense from a visual standpoint, both in code and in CSS. Styling the aforementioned border is trivial. However, as mentioned above, the semantics are fuzzy at best.

Thoughts, comments, questions?

Edit/Update Perhaps this was something I should have explicitly mentioned in relation to structure, but a definition list also has the problem of not semantically grouping the pairs. The ordering and implicit border between a dd and a dt is easily understood, but they still feel slightly off to me.

Re: your edit/update - if you wanted to ensure absolutely that there's no ambiguity about the semantic relationships between nodes you could always get really verbose and do
Name
Value 1
Value 2
but some would call that overkill. ;) — lucideer, Jul 19 '10 at 16:49
You should also ask about the CSS. E.g. `
` would be not so bad, but it is hard to style to display the pairs inline (like in table) — takeshin, Jul 19 '10 at 19:11
There have been many good answers, especially on the code side, but I'm still slightly hesitant about nearly all of them. This is only because every solution is a give-and-take. I will be marking one of the current answers as best for this thread soon, but know that it's a tough decision. — Ryan Kinal, Jul 20 '10 at 19:11
@Danny Lin's was the one! Semantics and style with ease thanks to the improved spec! https://stackoverflow.com/a/50313363/792888 — EvilDr, Oct 28 '19 at 14:27

score 68 · Accepted Answer · edited Feb 28 '15 at 10:13

Thanks for this interesting question. There are few more things to consider here.

What is a pair? Two elements together. So we need a tag for this. Let's say it is pair tag.

 <pair></pair>

The pair contains the key, and the corresponding value:

 <pair><key>keyname</key><value>value</value></pair>

Then, we need to list the pairs:

<pairlist>
     <pair><key>keyname</key><value>value</value></pair>
     <pair><key>keyname</key><value>value</value></pair>
</pairlist>

The next thing to consider, is the display of the pairs. The usual layout is the tabular one:

key value
key value

and the optional separator, which is usually colon:

key : value
key : value

The colons can be easily added via CSS, but this certainly won't work in IE.

Case described above is the ideal one. But there is no valid HTML markup to fit in this easily.

To sum up:

dl is semantically closest, for simple cases of key and value, but is hard to apply visual styles (eg. to display the pairs inline or to add red border to just hovered pair). The case which fits most for dl is glossary. But this is not the case we discuss.

The only alternative I can see in this case is to use table, like this:

<table summary="This are the key and value pairs">
    <caption>Some notes about semantics</caption>
    <thead class="aural if not needed">
        <tr><th scope="col">keys</th><th scope="col">values</th></tr>
    </thead>
    <tbody class="group1">  
        <tr><th scope="row">key1</th><td>value1</td></tr>
        <tr><th scope="row">key2</th><td>value2</td></tr>
    </tbody>
    <tbody class="group2">
        <tr><th scope="row">key3</th><td>value3</td></tr>
        <tr><th scope="row">key4</th><td>value4</td></tr>
    </tbody>
</table>

One more:

<ul>
  <li><strong>key</strong> value</li>
  <li><strong>key</strong> value</li>
</ul>

or:

<ul>
  <li><b>key</b> value</li>
  <li><b>key</b> value</li>
</ul>

or, when the keys may be linked:

<ul>
  <li><a href="/key1">key1</a> value</li>
  <li><a href="/key2">key1</a> value</li>
</ul>

The key and value pairs are usually stored in database, and those usually store tabular data, so the table would fit best IMHO.

What do you think?

Very thorough answer. I like how you showed your line of thought. +1 — Ryan Kinal, Jul 20 '10 at 19:09
and what about something like this: `

key
value

` whit that we can have arbitrary keys and values (a value could be another list, an image, etc.) — Enrique, Apr 20 '11 at 19:24
also, for the table solution maybe you could use the `` tag. Anyway, I think the table solution is not good, what happens if we can show the key and the value in different lines? — Enrique, Apr 20 '11 at 22:47
The verbosity of the table solution suggests against it's use, but an unordered list is pretty good. — Kzqai, Feb 20 '13 at 16:38
I believe (well, almost *know*) `` should be replaced by `` according to the HTML5 semantics. — Andreas Rejbrand, Jul 31 '13 at 20:54
This question is tops in Google. Could you please consider updating your answer to reflect @Danny Lin's input regarding the use of `div`s within `dl`? This solves the problem of semantics and styling, thus avoiding the noise of `` and ``: https://stackoverflow.com/a/50313363/792888 — EvilDr, Oct 28 '19 at 15:09

Danny Lin · Answer 2 · 2018-05-17T13:49:03.800

Following the specification (and further details) provided by Alexandr Antonov: use dl, dt, dd, and optionally div.

A combination of dl, dt, and dd is semantically fine for key-value pairs:

<dl>
    <dt>Key1</dt>
    <dd>Value1</dd>
    <dt>Key2</dt>
    <dd>Value2</dd>
</dl>

For easier styling or parsing, divs can be used as children of dl to group the key-value pairs (and makes dt and dd be grandchildren of dl):

dl { display: table; }
dl > div { display: table-row; }
dl > div > dt, dl > div > dd { display: table-cell; border: 1px solid black; padding: 0.25em; }
dl > div > dt { font-weight: bold; }

<dl>
  <div>
    <dt>Key1</dt>
    <dd>Value1</dd>
  </div>
  <div>
    <dt>Key2</dt>
    <dd>Value2</dd>
  </div>
</dl>

Excellent answer, and IMHO should be accepted answer, especially given the example included in the spec that fits this question perfectly. CSS Grid would also be a rather amazing way to format this simply and effectively. — EvilDr, Oct 28 '19 at 14:25

score 13 · Answer 3 · edited Jun 25 '18 at 09:58

13

XHTML 2 introduces the ability to group terms and definitions using the di element

<!-- Do not us this code! -->
<dl>
    <di>
        <dt>Name</dt>
        <dd>John</dd>
    </di>
    <di>
        <dt>Age</dt>
        <dd>25</dd>
    </di>
</dl>

X/HTML 5 vs XHTML 2 > Enhancement To Definitions Lists

Unfortunately though, XHTML 2 is dead and HTML5 doesn't have di element

So, you can combine ul > li with dl > dt + dd :

<ul>    
    <li>
        <dl>
            <dt>Name</dt>
            <dd>John</dd>
        </dl>
    </li>
    <li>
        <dl>
            <dt>Age</dt>
            <dd>25</dd>
        </dl>
    </li>
</ul>

edited Jun 25 '18 at 09:58

Manticore

1,284
16
38

answered Feb 27 '13 at 17:50

Yukulélé

15,644
10
70
94

7

Oh man. Wow. I want the `` element. I want it now. Too bad I can't have it. Thanks for the info, though! – Ryan Kinal Feb 27 '13 at 19:31
4

According to spec, `div` takes the role of `di`. See my answer for detail. – Danny Lin May 13 '18 at 06:33

score 6 · Answer 4 · answered Jul 19 '10 at 12:54

6

I think a definition list is probably a bad idea. Semantically, they are used for definitions. Other key-value lists will often differ from definition titles and descriptions.

A table is one way to go, but what about an unordered list?

<ul>
    <li class="key-value-pair">
        <span class="key">foo</span>
        <span class="value">bar</span>
    </li>
</ul>

answered Jul 19 '10 at 12:54

gpmcadam

6,346
2
33
37

2

Definition lists may be slightly poorly named in this regard, but they are not intended purely for definitions (they would be of fairly limited use case if they were) - the W3C spec. that defines them actually has an example of using them for marking up a dialogue. – lucideer Jul 19 '10 at 13:04
Thinking about it from an object-oriented standpoint, I suppose what I'm looking for is "an unordered list of name-value pairs", but I'm not sure this is the best answer (for now). +1 – Ryan Kinal Jul 19 '10 at 14:39
1

This is kind of microformat approach, but in default browser rendering or screen reader, you will get `foo bar`, like `foo bar` without any tags at all. One of the spans needs to be more than a span. Maybe ``? Then the second one is not needed. – takeshin Jul 19 '10 at 19:49
3

In the current [HTML5 spec](http://www.w3.org/TR/2011/WD-html-markup-20110405/dl.html#dl), dl has been rebranded as a description list which makes its use here seem more correct. – Eric Bock Apr 14 '11 at 13:39

Michiel Bruggenwirth · Answer 5 · 2018-09-29T20:24:12.833

6

dl {
  display: grid;
  grid-template-columns: auto auto;
}

dd {
  margin: 0
}

<dl>
  <dt>key</dt>
  <dd>value</dd>
  <dt>key</dt>
  <dd>value</dd>
</dl>

I used <dl> <dt> <dd> and styled them with grid

edited Sep 29 '18 at 20:24

answered Sep 29 '18 at 20:16

Michiel Bruggenwirth

71
2
5

Iiridayn · Answer 6 · 2016-08-02T20:01:05.157

This is not my preferred solution, but it is a clever abuse of the semantic element:

Use a new <dl> per <dt>/<dd> pair:

<div class="terms">
    <dl><dt>Name 1</dt><dd>Value 1</dd></dl>
    <dl><dt>Name 2</dt><dd>Value 2</dd></dl>
</div>

An example with css floats and red border on hover:

dt:after { content:":"; }
dt, dd { float: left; }
dd { margin-left: 5px }
dl { float: left; margin-left: 20px; border: 1px dashed transparent; }
dl:hover { border-color: red; }

<div class="terms">
    <dl>
        <dt>Name 1</dt>
        <dd>Value 1</dd>
    </dl><!-- etc -->
    <dl><dt>Name 2</dt><dd>Value 2</dd></dl>
    <dl><dt>Name 3</dt><dd>Value 3</dd></dl>
    <dl><dt>Name 4</dt><dd>Value 4</dd></dl>
    <dl><dt>Name 5</dt><dd>Value 5</dd></dl>
    <dl><dt>Name 6</dt><dd>Value 6</dd></dl>
</div>

Interesting. This would would work if it's not needed to be a list of related items... though I suppose one COULD encapsulate each `
` in an `

score 2 · Answer 7 · answered Jul 19 '10 at 13:16

it is difficult to properly offset the pairs visually, both in code and rendered. If I wanted to, for instance, but a border around each pair, that would be a problem.

Others before me have dealt (quite well I think) with the problem of providing visual definition in code. Which leaves the problem of rendering and CSS. This can be done quite effectively in most cases. The biggest exception is placing a border around each set of dt/dds, which is admittedly extremely tricky - perhaps impossible to style reliably.

You could do:

dt,dd{ border:solid; }
dt{ margin:10px 0 0 0; border-width:1px 1px 0 1px; }
dd{ margin:0 0 10px 0; border-width:0 1px 1px 1px; padding:0 0 0 10px; }
dd::before{ content:'→ '; }

Which works for key-value PAIRS, but presents problems if you have multiple dds within one "set" like:

<dt>Key1</dt>
  <dd>Val1.1</dd>
  <dd>Val1.2</dd>
<dt>Key2</dt>
  <dd>Val2.1</dd>
  <dd>Val2.2</dd>

However, border-styling limitations aside, doing anything else to associate sets (backgrounds, numbering, etc.) is quite possible with CSS. There's a nice overview here: http://www.maxdesign.com.au/articles/definition/

Another point I think is worth noting, if you're looking to optimally style definition-lists to provide visual separation - CSS's automatic-numbering features (counter-increment and counter-reset) can come in quite handy: http://www.w3.org/TR/CSS2/generate.html#counters

score 2 · Answer 8 · answered Jul 25 '16 at 17:42

Of course, you could just use HTML Custom elements. ( spec )They're completely valid HTML5.

Unfortunately, browser support isn't that great, but if rarely do we care about such pedestrian things as browser support when we're dealing with semantics. :-)

One such way you could represent it:

After registering your brand new fancy element like so:

var XKey = document.registerElement('x-key');
document.body.appendChild(new XKey());

You write markup like so:

<ul>
  <li>
    <x-key>Name</x-key>
    Value
  </li>
</ul>

The only condition that HTML Custom elements have are that they need a dash in them. Of course, you can now be super creative... if you're building an auto parts warehouse, with lists of parts and serial numbers:

<ul>
  <li>
    <auto-part>
      <serial-number>AQ12345</serial-number>
      <short-description>lorem ipsum dolor...</short-description>
      <list-price>14</list-price>
    </auto-part>
  </li>
</ul>

You can't get much more semantic than that!

However, there IS a chance I have gone too far into semantic-shangri-la-la (a real place) and might be tempted to scale it back to something a little more generic:

<ul>
  <li class='auto-part' data-serial-number="AQ12345">
      <p class='short-description'>lorem ipsum dolor...</p>
      <p class='list-price'>14</p>
  </li>
</ul>

Or perhaps this ( if I needed to style and show the key visually )

<ul>
  <li class='auto-part'>
      <x-key>AQ12345<//x-key>
      <p class='short-description'>lorem ipsum dolor...</p>
      <p class='list-price'>14</p>
  </li>
</ul>

Very interesting. I may look into this next time I'm in need of pairs. — Ryan Kinal, Aug 02 '16 at 16:05

score 1 · Answer 9 · answered May 31 '13 at 19:30

Except for the <dl> element, you've pretty much summed up all the options of HTML: limited ones.

However you're not lost, there is one option left: using a markup language that can be translated to HTML. A very good option is Markdown.

Using a table extension that some markdown engines provide, you can have code like this:

| Table header 1 | Table header 2 |
-----------------------------------
| some key       | some value     |
| another key    | another value  |

This means that you need a build step to translate the Markdown to HTML of course.

This way you get meaningful markup (table for tabular data) and maintainable code.

So you end up with a table again, but it's more work to get there. This doesn't seem like it solves any problems at all. — pydsigner, Jul 30 '16 at 20:46

score 1 · Answer 10 · answered Jul 19 '10 at 12:43

Hmm. dt/dd sound best for this and it is possible to offset them visually, although I do agree it's more difficult than for a table.

As for source code readability, how about putting them into one line?

<dl>
    <dt>Name</dt> <dd>Value</dd>
    <dt>Name</dt> <dd>Value</dd>
</dl>

I agree it's not 100% perfect, but seeing as you can use space characters for indentation:

<dl>
    <dt>Property with a looooooooooong name</dt>   <dd>Value</dd>
    <dt>Property with a shrt name</dt>             <dd>Value</dd>
</dl>

it might be the nicest way.

The problem is that under the spec, a `dt` can have more than one `dd` which may or may not be what is desired. — Armstrongest, Jul 25 '16 at 17:05

Dave Sag · Answer 11 · 2013-02-14T06:46:58.110

0

What about using lists?

Ordered:

<ol>
  <li title="key" value="index">value</li>
  …
</ol>

Or use <ul> for an unordered list, and skip the value="index" bit.

edited Feb 14 '13 at 06:46

answered Feb 14 '13 at 06:39

Dave Sag

13,266
14
86
134

score 0 · Answer 12 · edited May 31 '12 at 04:18

0

How about just placing a blank line between each pair?

This requires no special handling for long values.

<dl> 
    <dt>Name</dt> 
    <dd>Value</dd> 

    <dt>Name</dt> 
    <dd>Value</dd> 

    <dt>Name</dt> 
    <dd>Value</dd> 
</dl>

edited May 31 '12 at 04:18

dplante

2,445
3
21
27

answered Jul 19 '10 at 12:59

Philip Smith

2,741
25
32

White space characters don't have any semantic meaning in HTML. 1 space or multiple spaces, carriage returns `CR`, `tab`, and Line Feeds `LF` essentially all translate to a space. It's perhaps more visually appealing to a human reading the code, but it doesn't impart any semantic meaning. – Armstrongest Aug 02 '16 at 17:13

score 0 · Answer 13 · edited Jul 25 '16 at 17:11

0

The line from spec:

Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data.

I assume use of elements <dl>, <dt> and <dd>.

edited Jul 25 '16 at 17:11

Armstrongest

15,181
13
67
106

answered Jul 25 '16 at 16:43

Alexandr Antonov

1
1

2

Thanks for linking to the spec. Yes, the spec does allow for name-value pairs, but the `dl` element can be troublesome to display visually, as there is no container for each `key`/`value` pair. Its original use was likely for listing out glossary items or dictionary entries, which have 1 term and multiple definitions. – Armstrongest Jul 25 '16 at 17:11

score -1 · Answer 14 · answered Jul 19 '10 at 12:48

I do like Unicron's idea of putting them all on one line, but another option would be to indent the value below the definition name:

<dl>
    <dt>Name</dt>
       <dd>Value</dd>
    <dt>Name</dt>
       <dd>Value</dd>
</dl>

This way might be a little easier on the eye in ridiculously long definitions (although if you're using ridiculously wrong definitions then perhaps a definition list isn't what you really want after all).

As for the rendering on screen, a fat bottom margin applied to the dd is plenty visual separation.

Semantics and Structure of Name-Value Pairs

14 Answers14

Linked