Introduction

Writing clearly and unambiguously is essential for the drafting of specifications. This document takes a best practice that we have learnt in the past few decades and codifies them. Part 1 mainly aligns with the ISO Directive part 2, which takes particular care of the translatability of the document.

1. Scope

The scope of this document is

• to provide normative requirements to the OIDF documents; and
• to give guidance on the styles of writing such documents.

The targeted audience of this document is the people who will be an author of OIDF documents.

2. Normative references

• ISO Directive Part 2 (2021) ISODIR2

3. Terms and definitions

This document uses the following terms as the shortcut for complete wording provided as the definition. When the term appears within this document, it should be read as being replaced by the term.

The format of this clause is as follows.

3.1
provision

requirement and recommendation

3.2
finibus

de finibus bonorum et malorum
Note to entry: This definition is a shorthand for the title of a book by Cicero.

4. Abbreviations

5. Verbal forms for expressions of provisions

The documents following this directive shall use the following keywords to express requirement, recommendation, permission, and possibility.

Do not use “may” instead of “can”. “May” signifies permission expressed by the document, whereas “can” refers to the ability of a user of the document or to a possibility open to them.

In the cases where these keywords cannot be used for linguistic reasons, documents can use the equivalent phrases presented in Tables 3 to 7 of ISODIR2.

Unlike in the case of IETF, all keywords appear in small caps. This is because mixing SHALL, Shall, and shall make it extremely difficult to translate them into a language that does not have the notion of capital and small cases.

This means these keywords cannot be used in dictionary senses, which makes it possible to write more precisely.

NOTE: Alternatively, you may use RFC2119 keywords if you are drafting in IETF style. Just be mindful not to use small case versions of these keywords as it will make it difficult to translate.

6. Structure of the document body

6.1 Title

Title is a mandatory element.

1. Title shall have “draft” or “implementer’s draft” when it is not final.

2. Title should have its version number.

3. While the document is still not final, the title shall not have “OpenID” in it except when it is an extension/profile/binding of existing OpenID final specifications.

   Example: An entirely new (hypothetical) protocol draft “Avian carriers” is not allowed to use “OpenID Avian carriers” as its title, while “Avian carriers binding for OpenID Connect” is allowed.

This entry is not numbered.

6.2 Abstract

Abstract is an element that explains the content briefly. It is an optional element.

This entry is not numbered.

6.3 Warning

This is a mandatory element while the document is still a draft or implementer’s draft.

1. The document shall show the text as in this document.

This entry is not numbered. When the correct template is used with pandoc, it will be automatically inserted.

6.4 Notice

This is a mandatory element for all drafts, implementer’s drafts, and final specifications.

1. The document shall show the text as in this document.

When the correct template is used with pandoc, it will be automatically inserted.

6.5 Scope (Clause 1)

Clause 1 shall always be “1. Scope”. This clause explains what is in this document concisely and the targeted audience.

The scope clause gives the readers a compact description of what this document provides. Typically, it is drafted as a sentence split into several bullet points.

See clause 1 of this document to see an example.

This clause is mandatory.

6.6 Normative references (Clause 2)

Clause 2 shall always be “2. Normative references”. This clause lists all the documents that are essential to implement the requirements in this document. All other references shall be recorded in the Informative reference section at the end of this document.

Normative references section provides the list of documents that are essential to fulfil the requirements in this document. In other words, all the documents that are referred to with a “shall” shall be listed in this section.

Also, if the document includes the definition of another document, the document cannot be read without the included document. Therefore, such documents go into the normative reference.

This clause is mandatory.

6.7 Terms and definitions (Clause 3)

1. Clause 3 shall always be “3. Terms and definitions”. This clause is mandatory.
2. The first paragraph of clause 3 shall be the paragraph in Figure 1.

This document uses the following terms as the abbreviation for complete wording provided as the definition. When the term appears within this document, it should be read as being replaced by the term.

Figure 1 — The first paragraph in clause 3

NOTE: it will be automatically inserted if draft-template.html is used as the template for pandoc processing.

What this means is that if a term “finibus” was defined as “De Finibus Bonorum et Malorum”, then if “finibus” appeared in the text, it will be replaced with “De Finibus Bonorum et Malorum”. For example, when the text was:

Lorem ipsum is typically a corrupted version of Cicero’s “finibus”, with words altered, added, and removed to make it nonsensical, improper Latin.

a reader will read it as:

Lorem ipsum is typically a corrupted version of Cicero’s “De Finibus Bonorum et Malorum”, with words altered, added, and removed to make it nonsensical, improper Latin.

When there is ambiguity in the dictionary meaning of a term, it would be necessary to specify which definition is to be used in the document. For this, the editors should create an entry into clause 3.

3. An entry shall have the entry number as the first line, the preferred term as the second line, synonyms in the following lines, and the definition text in the following line.

EXAMPLE:

3.10
claims provider
attribute provider

IIP that provides attributes claiming they are true

When a term is defined, then any occurrence of the term should be able to be replaced by the definition. Because of this, there are several requirements on how terms and definitions are to be drafted.

A term

4. shall always be the small case;
5. shall be in the singular form, and
6. shall only appear here if it is used in the main text.

A definition

7. shall not start with an article;
   
8. shall not end with a punctuation mark; and
9. should be short.

It is advisable not to define a single word as it will make it not possible to use the word in a dictionary sense.

10. A verb should not be defined. Instead, the noun form should be defined.
11. The order of appearance of the terms shall not be alphabetic, as it will become meaningless when translated into another language.
12. The order of appearance should be

• according to the semantic relationship; or
• according to the appearance order in the document.

Editors are advised to replace all the defined terms in the document with the respective definitions and see if it reads well.

6.8 Symbols and abbreviations (Clause 4)

1. This clause’s title shall be one of the following according to the content of the clause.
   1. Symbols and abbreviations
   2. Symbols
   3. Abbreviations
2. All the symbols and abbreviations that appear in this document shall appear here.

This clause is optional.

6.9 Clause 5 and after

The main content of the text appears in clause 5 and after. It can span multiple clauses and subclauses.

When concepts are needed to be explained, do it here and after. Do not explain concepts in terms and definitions.

1. All figures and tables shall be numbered.
2. The document shall have text pointing to these tables and figures
3. Hanging paragraphs are not allowed as it will be difficult to differentiate if the pointer like 5.3 refers to the hanging pargraph or the entire 5.3.

6.10 Security considerations

Security considerations is a mandatory clause.

1. It should list out the security assumptions etc.

6.11 Privacy considerations

Privacy considerations are a mandatory clause.

1. The clause should list the potential privacy impacts that the deployment of the specification potentially causes.

6.12 Equity considerations

When appropriate, authors should write a clause on equity considerations. Considerations on accessibility, possible biases, etc. usually goes in here.

6.13 Appendixes

Appendixes are used to collect and present data, examples, etc. It is customary to list contributors in one of the appendices, so a document usually has at least one appendix.

During the drafting period, change history is also collected in the appendix.

1. Appendixes shall be labelled as Appendix A, Appendix B, etc.
2. The last appendix shall be the bibliography.
3. The second last appendix shall be the acknowledgement.
4. For drafts, there shall be an appendix collecting the document history, which will be removed from the final publication.

7. Drafting guidance

7.1 Simple and unambiguous English

When drafting the document, the editor should make sure that the language is simple and clear. This is particularly important as it will be a second language for many readers. In many cases, they have to rely on translations, and translations become harder as the sentence complexity rises.

To achieve the above goal, editors

1. should not use passive form;
2. should make a sentence short;

7.2 Addressable provisions

When showing compliance to a specification, one needs to be able to point to the provision exactly.

To achieve it, labelling them with a unique identifier is useful. Therefore,

1. one paragraph or list item shall have only one provision
2. the paragraph or list item shall be numbered or labelled.

Readers can refer to these provisions as 7.2-1 and 7.2-2.

It is possible to insert a paragraph, and then continue the numbers.

3. This line should appear as line item 3.
   1. subdivisions i.
   2. subdivisions ii.
4. This line should appear as line item 4.

7.3 Footnotes

Footnotes are possible. For example, RFC6749¹ can have the footnote as in this example.

7.4 Automatic numbering of clauses

Automatic numbering of clauses and subclauses are possible. To do so, use ‘-N’ commandline option for pandoc.

When using automatic numbering, make sure to put {.unnumbered} or {-} selector for the “Introduction”.

7.5 Pandoc commands

To create an HTML version of the document, use the following pandoc command.

% pandoc --toc -c site.css --template=draft-template.html -f markdown -t html -s --embed-resources -o outputfile.html inputfile.md 

where

• outputfile.html is a path to the output file
• inputifle.md is the source code markdown file
• draft-template.html is the OIDF template file that has legal notices etc.
• site.css is the CSS file to be embedded in the outputfile.html

8. Security considerations

Make sure that you are using the correct pandoc installation to convert the markdown file to HTML. If a compromised pandoc installation is used, it is possible that a malware code is to be included in the generated HTML file.

9. Privacy considerations

This document contains the authors’ and contributors’ names and contact.

1. They should be appropriately hidden before making it public.

10. Equity considerations

10.1 Accessibility

• This document is readable using a screen reader.
• This document is easier to process through a screen reader as it is not using cases to convey special meanings.
• This document is easy to translate as it is not using cases to convey special meanings.
• This document is provided as a self-contained HTML so it can be read by those without an internet connection.

Appendix A: Acknowledgement

This document was developed by OpenID Foundation.

Without the contribution of the following people, this document would not have been created.

Authors/Editors

• Nat Sakimura, NAT Consulting nat@nat.consulting
• Edmund Jay, Illumila ejay@mgi1.com

Contributors

• Alice Wonderland, Fairlytale
• Bob Spongy, Cartoon

Appendix B: Bibliography

Appendix C: Document History

• 2023-05-21 version 1
• 2023-06-22 version 2. Added IETF keywords provisions.