The current specification at https://daisy.github.io/ebraille/published/1.0/ is written in a wordy prose style, which is informationally sparse and where sections may not present information in the same sequence, sometimes where information may even be lacking. The short of this is that for a technical implementer it makes it very difficult to use the specification as a reference document to extract required information to create an implementation which will comply.

Whilst I will give examples below, these are only examples which are current in my mind due to the section of the specification I am currently implementing. So I am recommending the whole specification is reviewed and improved rather than just dealing with the specific examples I give here.

Example 1: How many instances of a given metadata item may appear in the OPF?

• For dc:language this is buried mid-section between examples.
• For a11y:brailleCellType it is stated at the end of the section.
• For dc:identifier 5.3.3.4 and dc:title 5.3.3.6 it is never explicitly stated although the text implies may be it is permitted for multiple.
• For dcterms:dateCopyrighted 5.3.3.7 and dcterms:dateModified 5.3.3.8 it is never said explicitly or implied.
• Section 5.3.3.13 actually discusses two properties and it is unclear which of these the statement "Only one instance of this property is allowed." at the end applies to. The fact a11y:graphicType appears in the required section would imply it must have a instance present, yet the examples seem to contradict this.

Example 2: What attributes may appear in a given metadata element? Similar inconsistent placement if explicitly stated issues as above.

Example 3: What is the permitted content values or structure of a given metadata element? Clarification this is things like true|false for a11y:tactileGraphics, iso8601-1 date for dcterms:dateCopyrighted. Again similar inconsistent placement issues, eg. 5.3.3.7 has it in the initial paragraph before examples where as 5.3.3.8 has it near the end after the examples and before the final note.

Another key information in metadata for implementers is the basic representation of the element, eg. a element in the dc namespace or a meta element with the property attribute set. This is may be in a better place in the specification due to the naming of the sections (IE. once one knows dc: means element in dc namespace and everything else tends to be meta with property).

The inconsistent placement of information, if information is actually even present, issue is exacerbated by the wordy prose nature of the specification. This makes the document text much longer and cluttered, meaning it is much more likely one will not spot the relevant information or may miss a detail. This is why I ask that the document to be rewritten into a more structured form where it is predictable where to find certain information within a section, may be even using structures to avoid the need for many words which may be needed for sentences but don't actually add meaning.

Here are a couple of example structures for tactile graphics which I think would make it much more readable and useful (I wanted to use tables but github doesn't seem to be working for markdown tables here):

a11y:tactileGraphics

Basic representation: <meta property="a11y:tactileGraphics">
Occurs: 1
Additional attributes: None
Content: true|false
Notes: Include a11y:graphicType when true

a11y:graphicType

Basic representation: <meta property="a11y:graphicType">
Occurs: 0-1
Additional attributes: None
Content: Comma separated list of image types
Notes: Must be included when a11y:tactileGraphic is true.

In the above for types which have no upper limit on how many times it may be included then asterisk could be used.