Writing dictionaries

How to write glossaries, books of quotations, timelines and more in the MyCodex dictionary XML.

Overall structure

The dictionary XML is a format for any collection of entries, not only word dictionaries. Each dictionary declares how its entries are sorted, how they are grouped and what fields they have.

<?xml version="1.0" encoding="UTF-8"?>
<Dictionary version="1" id="lawterms" title="My Legal Glossary" lang="en">
  <Kinds>
    <Kind id="term">Legal term</Kind>
  </Kinds>
  <Collections>
    <Collection id="civil">Civil Code</Collection>
  </Collections>
  <Fields>
    <Field id="importance" label="Importance" type="number" sortable="true" listVisible="true"/>
  </Fields>
  <Sorts>
    <Sort id="headword" label="A to Z" key="headword"/>
    <Sort id="importance" label="Most Important" key="field:importance" asc="false"/>
  </Sorts>
  <Browse group="collection"/>
  <Layout kind="headwordPrimary"/>
  <Entry> … </Entry>
  <Entry> … </Entry>
</Dictionary>

Everything except the entries (<Entry>) is optional, as long as there is at least one entry. The smallest dictionary is just <Entry> elements inside <Dictionary>.

<Kinds>, <Collections>, <Fields> and <Sorts> must always be written with their outer element. A <Kind> written directly under <Dictionary> is not read.

About the dictionary

The attributes of <Dictionary>:

Attribute	Meaning
`version`	Format version. Currently `1`. If omitted, it is read as 1
`id`	Dictionary ID. Other dictionaries link to it with this ID
`title`	Dictionary name. If omitted, it is shown as "Dictionary"
`lang`	Language: `ja` or `en`. The marks added to the text, such as quotation marks around examples, follow this language

Types and tags

A type is a category such as a part of speech; each entry has one. Tags (collections) can be added to an entry as many as you like.

<Kinds>
  <Kind id="term">Legal term</Kind>
</Kinds>
<Collections>
  <Collection id="civil">Civil Code</Collection>
  <Collection id="frequent">Common</Collection>
</Collections>

If you leave out id, the label itself becomes the ID.

The following parts of speech can be used by ID without being declared. Declare the same ID to change its label; in an English dictionary, declare the ones you use to give them English labels.

noun / properNoun / pronoun / verb / adjective / adjectivalNoun / adverb / adnominal / conjunction / interjection / particle / auxiliary / prefix / suffix / counter / phrase

Fields of your own

Add fields of your own, such as importance, year or speaker, with <Field>.

Attribute	Meaning
`id`	Field ID
`label`	Label
`type`	Kind of value: `text` (default) or `number`. Use `number` for fields you sort by number
`sortable`	Marks a field used for sorting. The sort options themselves are made with `<Sort>`
`groupable`	If `true`, entries can be grouped by this field
`searchable`	If `true`, the field is searched
`listVisible`	If `true`, the value is shown in the entry list

You can write 1 / 0 instead of true / false. Write a value inside an entry, as in <Field id="importance">5</Field>.

Sorting and grouping

Sorting: list <Sort> elements in <Sorts>. The first <Sort> is the order used when the dictionary opens. If there are none, entries are sorted by reading.

`key` value	Order
`reading`	By reading (`<Reading>`). Entries without a reading are sorted by headword
`headword`	By headword
`field:field ID`	By the value of a field of your own. To sort by number, set the field's `type` to `number`

Add asc="false" to reverse the order (largest or newest first).

Grouping: choose one with <Browse group="…"/>.

`group` value	Grouping
`none`	No grouping (default)
`kanaRow`	By the rows of the Japanese syllabary (あ, か, …)
`kind`	By type
`collection`	By tag
`field:field ID`	By the value of a field of your own

Layout

Choose how an opened entry looks with <Layout kind="…"/>.

headwordPrimary (default): the headword is shown large, as in a word dictionary.
contentPrimary: the text is shown large. Suits dictionaries where the text is the star, such as a book of quotations.

Entries

<Entry id="goodfaith" kind="phrase" collections="civil frequent">
  <Headword>good faith</Headword>
  <Variant>bona fide</Variant>
  <Field id="importance">5</Field>
  <Sense>
    <Definition>Being <Em>unaware</Em> of a particular fact. The opposite of <Ref entry="badfaith">bad faith</Ref>.</Definition>
    <Example>A third party in good faith is protected. <Source law="129AC0000000089" anchor="art_94_p2">Civil Code, Article 94(2)</Source></Example>
    <Note label="Note">It involves no moral judgment.</Note>
  </Sense>
  <Sense>
    <Definition>Honesty and fairness in dealing with others.</Definition>
  </Sense>
  <Etymology>From the Latin bona fides.</Etymology>
</Entry>

Element or attribute	Meaning
`id`	Entry ID. Other entries link to it with this ID
`kind`	Type. Only one
`collections`	Tags, separated by spaces or commas
`<Headword>`	Headword
`<Reading>`	Reading. Used for sorting by reading and grouping by syllabary row
`<Variant>`	Another spelling. You can write as many as you like, and they are searched
`<Sense>`	A sense. You can write as many as you like; with two or more, they are numbered ①, ② and so on
`<Definition>`	What the sense means
`<Example>`	An example, shown in quotation marks
`<Note>`	A note. Write its heading, such as "Note", in `label`
`<Etymology>`	Etymology
`<Source>`	Source. You can write it inside a sense or directly under the entry

The text is shown in this order: senses, etymology, then the entry's source, regardless of the order in the XML.

Text decorations

You can use these decorations in the text.

Markup	Display
`<Em>emphasis</Em>`	Bold
`<Em style="dots">dots</Em>`	Emphasis dots over the characters
`<Foreign>culpa</Foreign>`	Foreign term (italic)
`<Ruby>漢字<Rt>かんじ</Rt></Ruby>`	Ruby (reading aid)
`<Sup>up</Sup>` / `<Sub>down</Sub>`	Superscript / subscript
`<Line style="dotted">text</Line>`	Side line. `style` takes `solid` (default), `dotted`, `double` or `none`

For any other element, the tags are ignored and the text inside is shown.

Links

With <Ref> and <Source>, you can link to other entries, dictionaries, laws and web pages. Both take the same attributes.

Destination	Markup
An entry in the same dictionary	`<Ref entry="entry ID">…</Ref>`
Another dictionary	`<Ref dict="dictionary ID">…</Ref>`
An entry in another dictionary	`<Ref dict="dictionary ID" entry="entry ID">…</Ref>`
A law on e-Gov	`<Source law="law ID">…</Source>`
An article, paragraph or item of a law	`<Source law="law ID" anchor="art_94_p2">…</Source>`
A web page	`<Ref url="https://…">…</Ref>`

The law ID is the ID used on e-Gov Laws Search (the Civil Code is 129AC0000000089).

anchor points to an article, paragraph or item. Article 94 is art_94, Article 38-3 is art_38_3, Article 94, paragraph (2) is art_94_p2, and Article 94, paragraph (2), item (i) is art_94_p2_i1. You can also use the form at the end of e-Gov Laws Search URLs, such as Mp-At_94-Pr_2, as it is. Supplementary provisions and chapters cannot be targeted; the law opens at the beginning.

If you write more than one destination, the first of url, law, dict and entry is used.

Tips

Write text on one line. Line breaks and indentation inside <Definition> and similar elements are shown as spaces. Only <Example> trims spaces at the start and end.
Do not reuse an entry id within a dictionary. A dictionary with duplicate IDs cannot be imported.
If several entries share the same headword and reading, give them an id. Otherwise, entries may be mixed up after you sort them.
Start attribute names with a lowercase letter (title, listVisible). Mistakes in upper and lower case are still read, but element names must be exact.
If an attribute value is wrong (such as group="kanarow"), the import does not stop and the default value is used instead. If sorting or grouping does not work as expected, check the values.

Back to support home