Introduction

This document addresses authoring conventions and other points of XML Schema Definition (XSD) style in use by the Ed-Fi Alliance.

Audience

The audience for this page are developers, data modelers, and editors working on Ed-Fi XML Schema Definition files. These guidelines are used by the Ed-Fi Alliance development team for internal use, and are also the recommended styles for use when extending the core schema.

XSD Style Guide

This section covers the main points of style when authoring XSD. 

Naming Conventions

This section details many of the naming conventions to be employed when realigning, renaming and creating elements in the Ed-Fi Data Standard.

General Element Naming Guidelines

Abbreviations should be avoided in element or type names. Note, however, that "Id" is allowed when at the end of an element or type name.

Modifiers. In cases where multiple elements of similar type are used, the modifier should proceed the base element name (e.g., AssessedGradeLevel rather than GradeLevelAssessed)

Plurals. Avoid pluralization in element names.

Enumeration Rules

An enumeration is a list of values that are used to generate enumeration restrictions in the XSD. A name is required for each enumeration. A list of usable values must be supplied. Documentation can be added for both the enumeration and each value. When the logical name of the enumeration type is “Something Type”, instead of naming the XSD type SomethingTypeType, reduce the duplication and use the name in the style SomethingType.

Descriptor Rules

Descriptors are a customizable list of values that can be mapped to an Ed-Fi enumeration value. Documentation can be added for the descriptor. If the descriptor is part of Ed-Fi-Core.xsd, a mapping enumeration type can be defined and values provided. Additional system type, enumeration, and descriptor properties can be added to the descriptor, such as an enumeration representing a category or additional string properties.

Expansion Type Rules

Expansions represent a collection of properties in a reusable form. When referenced in another type, the XSD defines a child element for the expansion type. The expansion type can consist of system type, enumeration, descriptor, common, and domain entity reference properties. Documentation can be added for the expansion type and each of the properties.

Common Type Rules

Common types represent a collection of properties in a reusable form. When referenced in another type, a child element is defined on the declaring type. The common type can consist of system type, enumeration, descriptor, expansion, common, and domain entity reference properties. Documentation can be added for the common type and each of the properties. To allow a domain entity to have more than one value for this type, the properties that uniquely identify the data may be specified.

Domain Entity Rules

Domain entities represent the top level complex type for the Interchange. The domain entity type can consist of system type, enumeration, descriptor, expansion, common, and domain entity reference properties. Documentation can be added for the domain entity and each of the properties.

Other types can reference a domain entity type. When this occurs, the XSD defines an element that is a reference type for the domain entity.

Association Type Rules

Associations link two domain entities together with supporting properties. This relationship is used when there is not a clear parent/child relationship between the two entities. Documentation can be added for the association and each of the properties. To allow two domain entities to have more than one association for this type, additional properties that uniquely identify the data may be specified.

Annotation Style Guide

The Schema Annotation element can be added to most XML Schema elements. It specifies schema comments, which serve as inline documentation for the XSD. Ed-Fi Schema, particularly the Ed-Fi Core XML Schema, leverage Annotations heavily. This section outlines applicable points of style and usage.

Annotation text defaults to the Ed-Fi Technical Documentation Style Guide. Most of the style issues that pertain to Annotations have been called out here. Where not discussed herein, authors and editors should align with that guide.

General Annotation Guidelines

A vs. The. When referring to an element or concept generally, prefer the article “a” element (or “an” element) vs. “the” element. Thus “Specifies whether a course was defined by the state education agency, local education agency, school, or national organization.”

Annotations end with a period. Annotations end in a period even when as a simple sentence fragment.

Description vs. Prescription. Verb form should be appropriate for annotation subject; not an imperative to action. For example, a Discipline Incident Identity Type annotation “Provides user information…” rather than insists that one “Provide user information…”

Numbered list items. Numbered list item numbers are formatted with the number, followed by a period, followed by a space. The list items should not end with a period unless it’s a full sentence. For example:

1. First item
2. Second item
3. Third item

Numbered lists should be used only where there are a specific and finite number of items. If the list ends with “etc.,” or “…” then don’t use a numbered list. Numbered lists found within a sentence are generally separated by commas. For example, 1. first item, 2., second item, and 3., third item. (Note: Chicago Manual of Style 6.126 puts numerals in lists contained within a sentence in parentheses. Note also lower-case use on items as per Chicago style.)

Prepositions. Ending a sentence with a preposition is to be avoided. Reword sentence so that this does not happen. Example: Change “References the higher level the Assessment Family belongs to.” to read: “References the higher level to which the Assessment Family belongs.”

That vs. Which. For essential clauses, use “that” in place of “which.” “That” refers to a particular item under discussion. Unless preceded by a preposition such as “in which,” “which” should be preceded by a comma.

That vs. Who. “That” (and “which”) refers to non-humans; “who” refers to humans.

Style & Usage Guidelines

alphanumeric. No hyphen.

complex type. Lower case.

district. Lower case. This is the preferred general-purpose term for this entity. Most enumerations use “District” for this concept, so that seems like the most natural use. CEDS alignment note: CEDS uses LEA for the same concept. Where the schema has a specific alignment with CEDS, the term LEA may be found (and should not be changed).

Education Organization. The preferred form for annotations. Not “EdOrg” or “EducationOrganization” or “Educational Organization” or “Education Institution.”

e.g. and i.e. E.g. means “for example.” I.e. means “that is.” Use a comma after each (not a semicolon). Thus “e.g.,” Prefer these abbreviations inside parenthesis and the written out words “for example” or “that is” or "such as" outside of parenthesis and in full sentences. If “e.g.” or “i.e.” is used to prefix a list of examples, don’t use “etc.” at the end of the list. Example: “Used for days of the week (e.g., Monday, Wednesday).”

Element names. The Schema annotations usually refer to element names without making a distinction between the real-world entity and its abstraction in the schema. This ambiguity is usually okay because it doesn’t hinder understanding – but requires some judgment on the part of the annotation writer/editor to make the annotations look correct and consistent. Generally, these style rules should be followed:

• In cases where you’re explicitly referring to a real-world object and not the schema, follow the standard English spelling and capitalization.
• In cases where you’re discussing the schema element specifically, then use its name as it is in the Schema (i.e., with no space between words and with the schema capitalization). In addition, to make clear that you’re talking about a specific technical element, make that clear by adding an explanatory suffix. For example: “The association is an extension of the StudentProgramAssociation complex type particular to…” or similar.
• Most often, though, the annotations are following the general case that refers to both the real-world thing and the schema element. Always put a space between words (i.e., “Education Organization” vs. “EducationOrganization”). It’s the annotation author’s discretion whether capitalize element names – just do so consistently when it occurs in a grouping of associated annotations (e.g., in a complex type).

etc. Not etc or etcetera. Also see note at e.g.

for example. The rule of thumb is to use “e.g.” inside parenthesis and “for example” outside of parenthesis. Annotations should generally prefer “e.g.” when simply listing examples expresses the point well. However, “for example” may be used when the examples are part of a passage meant to illuminate the reader beyond a simple list, or when a conversational tone is useful, or as the introduction to a bulleted/numbered list. Lists of items preceded by "for example" may end in "etc."

lookup. Okay to use in XSD annotations. This is a special usage verb that means to find a referenced record in a database or other system via external properties. Also used as a noun to mean the property or bundle of properties used to perform the lookup. Lower case, one word. Note that “look up” as a verb phrase is okay if used generically or in an example.

nonschool. Allowable in XSD. Thus in CEDS documentation and U.S. DoE Data Handbook, so okay in comments. (See, e.g., CEDS/DoE Code ID 03059.)

postsecondary. No hyphen (i.e., not post-secondary).

U.S. Abbreviated thus (i.e., not US, or U.S.A. or US of A, or U. to the S. of A., or similar).