Widget References & Standards API Routing

[PROPOSED Late 2022] Structured References

Format

To allow for references to directly link to relevant standards/codes, a structured array format is proposed for a new field (referencesJSON):

The “description” field will not be part of the first iteration, as further user testing on its benefits will be conducted.

[
  // STANDARDS API
  {
        "id": "/api/standards/AISC/AS4100_2020_1/section/5.6.3",
        "name": "AS 4100:2020, Cl 5.6.3",
        "description": "Non-compact Sections"
  },
  // EXTERNAL RESOURCE
  {
        "id": "https://awc.org/publications/2018-nds-supplement/",
        "name": "NDS 2018 Supplement, Table 5B",
        "description": "Reference Design Values for Structural Glued Laminated Softwood Timber (Members stressed primarily in axial tension or compression)"
  }
]

Field Descriptions

Field	Usage / Type	Description
id	Relative or Absolute URL	Relative URLs display as a button opening in the standards sidebar. Absolute URLs display as links with text equal to the `name` field below. Absolute URLs should point to an internet copy or purchase link and are mandatory.
name	Free-text field	What appears on the button for standards access, or the hyperlink text for external resources. Should be the full standard name & clause. For standards API, this auto-populates based on the `id` URL.
description	Free-text field	Text shown to the right of button/link. Should be the exact title of the clause/section/figure/table, with minimal additional context (use widget `description` field for clarifications).

Standards API Links

The standards API intention is full search support in the Builder. All metadata can be generated automatically by searching for relevant clauses in a text box.

Example Workflow

Type AS4100 Cl 5.6.3 in search
Standards API suggests matches
On selection, creates:
- id: Relative URL for standards API [www.calcs.com/api/standards/[ID]
- name: Clause name for the button
- description: Auto-populated title of specific clause/section/figure/table

Standards Examples

Examples for Standards Australia & AISC integrations:

[
    {
        "id": "/AS/AS4100_2020_1/section/5.6.3", 
        "name": "AS 4100:2020, Cl 5.6.3",
        "description": "Non-compact Sections" //if label exists in standard
    },
    {
        "id": "/AISC/AISC-360-16/section/B4.2",
        "name": "AISC 360-16, Cl B4.2",
        "description": "Design Wall Thickness for HSS"
    }
]

External References

The id field is mandatory. Many product catalogues, technical notes and standards authorities provide direct links or purchase pages.

External Reference Examples

[
    {
        "id": "https://awc.org/wp-content/uploads/2021/12/AWC-TR14-0312.pdf",
        "name": "AWC TR14, Cl 2.1.3.4",
        "description": "Load Eccentricity Factor for Beams Loaded on the Compression-Side"
    },
    {
        "id": "https://www.weyerhaeuser.com/application/files/9915/3022/3376/TJ-1020.pdf",
        "name": "Weyerhauser TJ-1020", // note the main document, not a clause
        "description": "Preservative Treatments Approved for Trus Joist® Engineered Wood Products"
    },
    {
        "id": "https://awc.org/publications/2018-nds-supplement/",
        "name": "NDS 2018 Supplement, Table 5B",
        "description": "Reference Design Values for Structural Glued Laminated Softwood Timber (Members stressed primarily in axial tension or compression)"
    },
    {
        "id": "https://awc.org/pdf-viewer/?idp=1414&idf=2",
        "name": "NDS 2018 2.3.2",
        "description": "Load Duration Factor, CD(ASD Only)"
    },
    {
        "id": "https://www.aisc.org/globalassets/aisc/publications/standards/a360-16w-rev-june-2019.pdf",
        "name": "AISC 360-16, Cl B4.2",
        "description": "Design Wall Thickness for HSS"
    }
]

Transition of Existing Templates

To be confirmed. Scripts will be used for automation where possible, followed by manual updates.

ID Field Standards URL Structure

Format: /Authority/Standard/type/Type-reference/sub-type/Sub-type-reference

Lower-case for enumerations of select types
Upper-case for dynamic references

Authority

The Standards provider. E.g., SA (Standards Australia), AISC, ACI, etc.

Standard

Unique identifier for the standard document with hyphens as separator: PREFIX-CODE-YEAR-REVISION

PREFIX: AS, AISC, ASNZS, etc. [required]
CODE: 4100 or 1720-1 (for AS), 360 (for AISC) [required]
YEAR: YYYY (for AS), YY (for AISC) match the standard default [required]
REVISION: 1 (for AS Amdt 1). Not necessarily correlated with actual amendment number [optional]

Examples:

AS-4100-2020-1 (AS4100:2020 incorporating Amdt 1)
AS-4100-Supp1-1999 (AS4100 Supplement 1 - 1999)
AS-1720-1-2010-3 (AS1720.1:2010 incorporating Amdt 1-3)

Type / Type-reference

Hyphen-separated clause reference with unique identifiers in standards documents.

Section

Main sections within document or appendix (2-4 layers depth: X-X to X-X-X-X):

section/5-6-3 (Cl 5.6.3 in AS4100)
section/H-5-2-2 (App H Cl H.5.2.2 in AS4100-2021)
section/I-6-1 (Clause I6(1) - AISC AS360-16)
section/I-6-2-a (Clause I6(2a) - AISC AS360-16)

Table / Figure

Tables with unique title references (2-4 layers depth: X-X to X-X-X-X):

table/5-6-2
table/5-6-3A (Table 5.6.3(A) in AS4100)
table/B-1 (Table B1 in appendix B)
figure/9.1.10.3B (Figure 9.1.10.3(B) in AS4100)

Equation

Must have unique references (only partially covered in newer Australian standards):

equation/9-2-2-4 (for 9.2.2.4(2) in AS4100)

Sub-type / Sub-type-reference [OPTIONAL]

1-4 layers depth supported (X to X-X-X-X). Most common is list for section/table/equation list items.

Examples:

section/5-6-2/list/b-i (AS4100 Cl 5.6.2(b)(i))
table/A-3-1/list/2-1-a (Table A-3.1 reference 2.1(a) AISC A360-16)
equation/9-2-2-4/list/2 (for 9.2.2.4(2) in AS4100)

Markdown Support

Supported markdown elements in widget description sections:

Element	Markdown Syntax
Bold	`bold text`
Italic	`italicized text`
Code	`code`
Fenced Code Block	```
Link	`[title](https://www.example.com)`

Not all markdown features are supported in the description sections of widgets.

​Widget References & Standards API Routing

​[PROPOSED Late 2022] Structured References

​Format

​Field Descriptions

​Standards API Links

​Example Workflow

​Standards Examples

​External References

​External Reference Examples

​Transition of Existing Templates

​ID Field Standards URL Structure

​Authority

​Standard

​Examples:

​Type / Type-reference

​Section

​Table / Figure

​Equation

​Sub-type / Sub-type-reference [OPTIONAL]

​Examples:

​Markdown Support

Widget References & Standards API Routing

[PROPOSED Late 2022] Structured References

Format

Field Descriptions

Standards API Links

Example Workflow

Standards Examples

External References

External Reference Examples

Transition of Existing Templates

ID Field Standards URL Structure

Authority

Standard

Examples:

Type / Type-reference

Section

Table / Figure

Equation

Sub-type / Sub-type-reference [OPTIONAL]

Examples:

Markdown Support