STAR syntax by example

The easiest way to understand STAR syntax is to look at a real example.

Below is a use case (LogOnCustomer.uc) written in STAR. This use case uses the schema UseCase.sss that comes with STAR. This schema defines the tags that we use in the use case:

 :schema:
 UseCase.sss

 :name:
 LogOnCustomer

 :id:
 18

 :parents:
 1. None

 :primaryActor:
 Customer

 :secondaryActors:
 1. None

 :brief:
 The system automatically logs the Customer on to the site.

 :pre:
 1. The Customer is not logged on to the system.

 :flow:
 1. The use case begins when the Customer actor accesses the first page of the website.
 2. The system automatically recognises the Customer.
 3. The system automatically logs the Customer on to the site.

 :post:
 1. The Customer is logged on to the system.

 :alt:
 1. LogOnCustomer.ExistingCustomerNotRecognized
 2. LogOnCustomer.CustomerLogOnFails

 :req:
 1. None

If you know anything about use cases, then this example should be self explanatory.

The structure of a STAR document is a tag (e.g. :schema:) followed by one or more lines, followed by a blank line, repeated.

Each STAR document may have a special tag of the form:

 :schema:
 SchemaName.sss

that specifies the STAR schema that will be used to validate the document.

Here is the schema (UseCase.sss) for this use case:

 :schema:
 UseCase.sss    

 :name:
 Write the name of the use case here. Use case names are in UpperCamelCase with no spaces.

 :id:
 Write the unique project identifier for the use case here.

 :parents:
 Write the names of the parent use cases here. If this use case has no parents write None here.

 :primaryActor:
 Write the name of the primary actor here.

 :secondaryActors:
 List the names of the secondary actors here.
 Secondary actors participate in the use case, they do not start the use case.
 If there are no secondary actors, write None here.

 :brief:
 Write a brief description of your use case here.
 This description should be no more than a couple of paragraphs.

 :pre:
 Write the first precondition here.
 If the use case has no preconditions, write None here.

 :flow:
 Write the main flow here.
 Each step should be time-ordered and declarative.
 :ex:WriteExtensionPointsLikeThis
 Note that extension points are NOT numbered.
 If you need to show nested steps
  Indent them by one space for each level of indent like this.
 Include other use cases like this :inc:AnotherUseCase.
 This is the final step.

 :post:

 Write the postconditions here.
 If there are no postconditions write None here.

 :alt:
 List the names of the alternative flows here, one on each line.
 If there are no alternateive flows, write None here.

 :req:
 List any special requirements  related to the use case here. These are typically non-functional requirements.
 If there are no special requirements, write None here.

As you can see, STAR schema are written in STAR. In fact, they are really just exemplar documents. If they are written well, they are also self-documenting and describe the semantics of the tags.

STAR document syntax

STAR syntax is very simple. There are:

• Section tags
• Inline tags

Tags are subject to the constraint that each tag in a document must be unique.

Each section tag is of the form:

 :tagName:
 A line of text
 Another line of text
 <BLANK LINE>

Each section tag is followed by one or more lines of text that constitute the content of the tag. Indentation of lines (whitespace or a + sign at the beginning of the line) is significant. STAR tools might use indentation to autonumber lines or nest lines in a tree structure.

Each section tag is terminated by a blank line.

Inline tags are of the form:

 Some text :inlineTagName:OptionalInlineTagContent some more text.

Section tags are defined in STAR schema. Inline tags are currently not part of the schema (although we will be adding them shortly). 

Any STAR document that uses this tag syntax is a well-formed document. If the document also specifies a schema, and conforms to the constraints specified in that schema, then it is valid.

STAR schema syntax

STAR schema are just exemplar STAR documents with the extension .sss. They have the same syntax as STAR documents but are interpreted by STAR tools as schema that constrain other documents as follows:

• The section tags in the STAR schema define the allowed section tags in all valid STAR documents that use the schema
• The number of lines after a section tag determines the multiplicity of the tag.

The multiplicity of a tag defines the maximum number of lines that valid STAR documents may have after the tag. STAR tools may use tag multiplicity as part of the validation process for STAR documents. Tag multiplicity is specified in STAR schema as follows: if there is one line after the schema tag, the tag has multiplicity 1, if there is more than one line, the tag has multiplicity * (many).

STAR schema should always be written so that they are self-documenting. Rather than using a schema dialect (like XML Schema) and possibly separate documentation for tag semantics, STAR schema are simply exemplar STAR documents that contain the tag semantics.