- Created by Robert Reiner, last modified on 11. Mar 2020
Describes the doctypes model.
- Location
src/main/resources/projectdoc-models/doctypes/
The Doctype XSD defines doctypes to create page blueprints.
Examples
The following list shows examples of doctype descriptors.
- Discoverybility Example
- An example of a simple type-like doctype.
- Doctype with Type Example
- An example of a doctype with a doctype-specific type.
- Security View Example
- A more detailed doctype declaration with non-standard properties and sections.
Details
Here are some aspects of using the doctype XSD to specify doctype descriptors.
Base Template
Base templates provide standard properties and sections. Typically documents should be based on the standard template.
<doctype xmlns="http://smartics.de/xsd/projectdoc/doctype/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="my-doctype" base-template="standard"> ... </doctype>
The following templates are provided.
- standard
- Provides the standard properties and sections.
- type
- Provides properties and sections required by categorizing document types.
- empty
- Provides no properties and sections.
The Doctype XSD lists all valid types. Currently users cannot define their own templates without getting hands on the source code.
Provide Type
If the attribute provide-type of the doctype element is set to the name of a type template, a type doctype based on that type will be generated. This type document is used as a doctype-specific category to organize document instances for that type.
If you have a doctype resource with this property set to 'true', an additional doctype named resource-type will be generated. Types for resources may be 'Article', 'Website', or 'Podcast'.
Two values are currently allowed: none for providing no type (default), and standard-type.
<doctype xmlns="http://smartics.de/xsd/projectdoc/doctype/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... provide-type="standard-type" ...>
Has Homepage
Signals whether or not the doctype has its own homepage. This defaults to true, so there is a homepage for the doctype.
<doctype xmlns="http://smartics.de/xsd/projectdoc/doctype/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... has-homepage="false" ...>
Wizard Configuration
If there is no homepage, the generated wizard for the doctype should usually provide means to send a new page to its default location.
Use the following wizard configuration to omit the Target Homepage element.
<wizard template="no-homepage" />
Related Doctypes
The related-doctypes element within the doctype element contains a list of doctype IDs. Links to the mentioned doctypes are added to index pages and home pages as references.
<related-doctypes> <id>affected-users</id> <id>damage-potential</id> <id>discoverability</id> <id>exploitability</id> <id>mitigation-level</id> <id>reproducibility</id> <id>threat-type</id> </related-doctypes>
Category
Reference one of the categories defined with the add-on descriptor.
<doctype xmlns="http://smartics.de/xsd/projectdoc/doctype/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... category="threat-aspect">
Metadata
A doctype may provide additional metadata.
<metadata> <property key="projectdoc.doctype.common.is-a">aspect</property> </metadata>
Key and value of a metadata entry must be character sequence.
Metadata is added as artificial properties to a projectdoc document.
Since projectdoc Toolbox 4.5
The key projectdoc-materialize allows to define default materializations of document properties.
The property value is a property path, with the internationalization key referencing the localized name of the property.
<metadata>
<property key="projectdoc-materialize">
projectdoc.doctype.common.tags->projectdoc.doctype.common.type,
projectdoc.doctype.common.type->projectdoc.doctype.common.sortKey
</property>
</metadata>
Property Value
The contents of the property value element may contain
arbitrary XML within an
xmlelement.a macro definition.
- a placeholder.
XML
<property key="projectdoc.doctype.common.iteration">
<value>
<xml><![CDATA[<ac:structured-macro ac:name="projectdoc-iteration">
<ac:parameter ac:name="value">production</ac:parameter>
</ac:structured-macro>]]></xml>
</value>
</property>
Macro
<property key="projectdoc.doctype.common.type">
<value>
<macro name="projectdoc-name-list">
<param name="doctype">security-view-type</param>
<param name="property" key="projectdoc.doctype.common.type" />
<param name="render-no-hits-as-blank">true</param>
</macro>
</value>
...
</property>
Placeholder
<property key="projectdoc.doctype.security-view.service">
<value>
<placeholder key="projectdoc.doctype.security-view.service.placeholder" />
</value>
...
</property>
Since this is the default configuration, you may omit the value element completely.
<property key="projectdoc.doctype.security-view.service"> ... </property>
Section
Doctype Description
A section may override the description section's placeholder. This is helpful to provide page authors with specific help on what to add to the description section's body.
<section key="projectdoc.doctype.common.description">
<resource-bundle>
<l10n>
<description>
Provide a view on a service from the security perspective. Describe
the service briefly and link to
it for further information.
</description>
</l10n>
<l10n locale="de">
<description>
Erstellen Sie eine Sicht auf einen Service aus der
Sicherheitsperspektive. Halten Sie die
Beschreibung kurz und
fokussieren Sie auf die Belange der Sicherheit. Verweisen Sie auf die
Servicedokumentation für weitere Informationen.
</description>
</l10n>
</resource-bundle>
</section>
This works for all sections that only provide a placeholder text. The key may be a local internationalization (I18N) key.
The following example shows how the common description (provided by the standard doctype), the common summary (not provided by the standard doctype), and a doctype specific sections is specified. All three will render its placeholder text in the section body.
<sections>
<section key="projectdoc.doctype.common.description">
<resource-bundle>
<l10n>
<description>
Describe the reason why this step is valuable and what readers may
learn from reading this document.
</description>
</l10n>
<l10n locale="de">
<description>
Beschreiben Sie, warum dieser Schritt wichtig ist und was Leser
dadurch lernen können.
</description>
</l10n>
</resource-bundle>
</section>
<section key="projectdoc.doctype.common.summary">
<resource-bundle>
<l10n>
<description>
Describe what is the result of taking this step or what can be
learned after finishing this step.
</description>
</l10n>
<l10n locale="de">
<description>
Beschreiben Sie zusammenfassend, was die Erkenntnisse aus diesem
Schritt sind oder was das Ergebnis dieses Schritts ist.
</description>
</l10n>
</resource-bundle>
</section>
<section key="projectdoc.doctype.step.actions">
<resource-bundle>
<l10n>
<name>Actions</name>
<description>
Describe what has actually been done to execute this step. This may
include screenshots and more than one step. If there are too many
steps that need to be explained, add additional step documents as
children to this document.
</description>
</l10n>
<l10n locale="de">
<description>
Beschreiben Sie die Durchführung dieses Schritts in einzelnen
Aktionen. Dies kann Screenshots beinhalten. Wenn die einzelnen
Aktion noch immer sehr komplex ist und einer ausführlichen
Erläuterung bedarf, kü6nnen sie die einzelnen Schritte auch in
eigenen Teildokumenten beschreiben und diesem Dokument als Kinder
anfügen.
</description>
</l10n>
</resource-bundle>
</section>
</sections>
XML
The section allows to specify an arbitrary document part in the storage XML format.
Please note that the section marco needs to be specified. Technically you could add elements that are no section macros.
<section key="projectdoc.doctype.security-control.mitigation-strategies">
<xml><![CDATA[<ac:structured-macro ac:name="projectdoc-section">
<ac:parameter ac:name="title"><at:i18n
at:key="projectdoc.doctype.security-control.mitigation-strategies"/></ac:parameter>
<ac:parameter ac:name="intro-text"><at:i18n
at:key="projectdoc.doctype.security-control.mitigation-strategies.intro"/></ac:parameter>
<ac:rich-text-body>
<ac:structured-macro ac:name="projectdoc-display-table">
<ac:parameter ac:name="doctype">mitigation-strategy</ac:parameter>
<ac:parameter ac:name="render-no-hits-as-blank">true</ac:parameter>
<ac:parameter ac:name="restrict-to-immediate-children">true</ac:parameter>
</ac:structured-macro>
</ac:rich-text-body>
</ac:structured-macro>]]></xml>
<resource-bundle>
<l10n>
<name>Mitigation Strategies</name>
<intro>List of strategies to mitigate the impact of a potential threat.</intro>
</l10n>
<l10n locale="de">
<name>Strategien zur Abschwächung</name>
<intro>Liste Vorgehensweisen, um die Wirkung möglicher Bedrohungen abzuschwächen.</intro>
</l10n>
</resource-bundle>
</section>
If the XML snippet contains additional I18N keys, use the label element to provide localized information for them.
<resource-bundle prefix="projectdoc.doctype.configuration-item">
<l10n>
<name>Dependencies</name>
<label key="list-of-documentation-assets">Documentation Assets</label>
<label key="list-of-documentation-assets.intro">This configuration item is
described in the following documentation assets.</label>
...
Note that the prefix specified with the resource-bundle element is prepended to each label element's key attribute value. So in the XML snippet of this example the following keys are used:
projectdoc.doctype.configuration-item.list-of-documentation-assets
projectdoc.doctype.configuration-item.list-of-documentation-assets.intro
Resources
More information on projectdoc models:
- Add-on Descriptor
- Describes add-on level elements of the projectdoc model.
- Space Descriptor
- Describes the spaces model. Currently only one space per add-on is supported.
