ZONTAL Studio - ASM Language Features

ZONTAL Studio - ASM Language Features provides language support for Allotrope Simple Model (ASM) files (.asm) plus Turtle (.ttl) and N-Triples (.nt).

BETA: This extension is in active development. Features and behavior may change, and cached resource formats may evolve between releases.

Features

• Syntax highlighting for asm, turtle, ntriples.
• ASM formatting (JSON-safe).
• Manifest-based IntelliSense and validation.
• Manifest-based hover (property/value documentation from JSON Schema).
• Clickable links for http(s)://... IRIs.

Editing ASM with Visual Studio Code

Allotrope Simpe Model (ASM) is a data format that is common in data-driven research, analysis, and collaboration across various scientific disciplines. When opening a file that ends with .asm, ASM Language Features provides features to make it simpler to write or modify the file's content.

Change the language for the selected file

In VS Code, we default the language support for a file based on its filename extension. However, at times you may want to change language modes, to do this click on the language indicator - which is located on the right hand of the Status Bar. This will bring up the Select Language Mode dropdown where you can select another language for the current file.

Tip: You can get the same dropdown by running the Change Language Mode command (Ctrl+K M).

IntelliSense and validation

For properties and values we offer up suggestions as you type with IntelliSense.

We also perform structural and value verification based on the associated ASM manifest giving you red squiggles. To disable validation, use the studioASM.asm.validate.enable setting.

You can also manually see suggestions with the Trigger Suggestions command (Ctrl+Space).

Quick navigation

ASM files can get large and we support quick navigation to properties using the Go to Symbol command (Ctrl+Shift+O).

Hovers

When you hover over properties and values for ASM data with manifest, we will provide additional context.

ASM Language Features will use the standard description field from the JSON Schema specification in order to provide information about properties on hover and during autocomplete.

• [ ] TODO: Enrich hover with vocabulary information.

Formatting

You can format your ASM document using Shift+Alt+F or Format Document from the context menu.

Folding

You can fold regions of source code using the folding icons on the gutter between line numbers and line start. Folding regions are available for all object and array elements.

ASM manifests

To understand the structure of ASM files, we use ASM manifests. ASM manifests describe the shape of the ASM file, as well as value sets, default values, and descriptions. The ASM support shipped with this extension supports all versions.

Servers like the Allotrope-Public Gitlab Repository provide manifests for commonly used techniques. However, manifests can also be defined in a file in the VS Code workspace.

The association of an ASM file to a manifest is done in the ASM file itself using the $asm.manifest attribute.

Mapping in the ASM

In the following example, the ASM file specifies that its contents follow the Plate Reader manifest.

ASM

{
  "$asm.manifest": "https://purl.allotrope.org/manifests/plate-reader/REC/2025/12/plate-reader.manifest"
}

Resource caching model

This extension caches downloaded resources under the .asm_cache/** directory.

• Directory catalogs (listing only) are stored under .asm_cache/directories/**/catalog.json for directory sources that need them (for example the built-in GitLab listings).
• Workspace directories are scan-based (glob search) and do not write catalogs.
• When resources change, the extension clears related in-memory caches and revalidates open documents.

If you delete .asm_cache, the extension will repopulate directory catalogs and downloaded files as needed (configurable).

Network access

To populate caches, the extension may fetch resources from:

• https://gitlab.com/allotrope-public/asm (Allotrope public ASM repository) for manifests and JSON schemas.
• http://purl.allotrope.org for TTL shapes/vocabulary referenced by cached manifests.
• Any recource referenced by ASM Manifest or JSON Schema $ref (on-demand), which is then cached into .asm_cache/**.

No telemetry is collected by this extension.

Offline mode

The studioASM.download.enable setting controls whether the extension fetches resources from http and https.

A warning triangle will show in the status bar when the current editor would like to use resources that cannot be downloaded.

Logging

This extension logs diagnostic and operational messages to VS Code Output channels (to help troubleshoot catalog creation, caching, schema resolution, and language features).

To view logs:

• Open View → Output.
• Select the Studio ASM channel from the dropdown.

To avoid spamming the Output view, many messages are rate-limited (logged with a TTL, typically a couple seconds per unique message key). Some user-facing warnings are also TTL-limited.

Commands

This extension contributes the following commands:

• Studio ASM: Open Resource: opens the resource file if present, otherwise opens the URL in VS Code’s Simple Browser.
• Studio ASM: Refresh Resource Catalogs: refreshes directory listings and workspace id mappings (does not download resource contents).

Extension Settings

ASM Language Features contributes the following settings:

Feature settings:

• studioASM.asm.completions.enable (default: true): enable schema-based completions for ASM files.
• studioASM.asm.formatting.enable (default: true): enable formatting for ASM files.
• studioASM.asm.hover.enable (default: true): enable schema-based hover documentation for ASM files.
• studioASM.asm.links.enable (default: true): enable clickable resource links for URLs in ASM files.
• studioASM.asm.symbols.enable (default: true): enable document symbols (Outline/Breadcrumbs) for ASM files.
• studioASM.asm.validate.enable (default: true): enable schema-based validation for ASM files.
• studioASM.json.completions.enable (default: true): enable schema-based completions for JSON files.
• studioASM.json.links.enable (default: true): enable clickable resource links for URLs in JSON files.
• studioASM.json.validate.enable (default: true): enable schema-based validation for JSON files.
• studioASM.turtle.hover.enable (default: true): enable hover that resolves prefixed names (e.g. rdf:type) to fully-qualified IRIs in Turtle (.ttl) files.
• studioASM.turtle.links.enable (default: true): enable clickable resource links for URLs in Turtle (.ttl) files.
• studioASM.turtle.symbols.enable (default: true): enable document symbols (Outline/Breadcrumbs) for Turtle (.ttl) files.
• studioASM.validation.strict (default: true): flag unknown properties not defined by JSON Schemas (helps catch typos).

Online/Offline settings:

• studioASM.download.enable (default: true): controls whether the extension fetches resources from http and https.

Resolution settings:

• studioASM.resolutions.jsonPatterns (default: ["!**/shapes/**/*", "!**/voc/**/*"]): glob patterns used to classify resource IDs as JSON resources.
• studioASM.resolutions.ttlPatterns (default: ["**/shapes/**/*", "**/voc/**/*"]): glob patterns used to classify resource IDs as TTL resources.

Directory settings:

• studioASM.autoInitializeCatalogs (default: true): initialize directory catalogs on activation (best-effort).

• studioASM.directories.manifests.globPatterns (default: ["**/manifests/**/*.json"]): workspace glob patterns used to list manifest files.

• studioASM.directories.schemas.globPatterns (default: ["**/schemas/**/*.json"]): workspace glob patterns used to list schema files.

• studioASM.directories.shapes.globPatterns (default: ["**/shapes/**/*.ttl"]): workspace glob patterns used to list shapes files.

• studioASM.directories.vocabulary.globPatterns (default: ["**/vocabulary/**/*.ttl"]): workspace glob patterns used to list vocabulary files.

Extension API

Other VS Code extensions can consume a programmatic API from this extension.

• Extension id: zontal.vscode-asm-language-features
• Access pattern: const api = await vscode.extensions.getExtension('zontal.vscode-asm-language-features')?.activate();

The returned API exposes:

• registerManifestDirectory(service: DirectoryService): void

• registerSchemaDirectory(service: DirectoryService): void

• registerShapesDirectory(service: DirectoryService): void

• registerVocabularyDirectory(service: DirectoryService): void

• registerResolution(service: ResolutionService): void

• listManifestUris(): Promise<vscode.Uri[]>

• listSchemaUris(): Promise<vscode.Uri[]>

• listShapesUris(): Promise<vscode.Uri[]>

• listVocabularyUris(): Promise<vscode.Uri[]>

• resolveUri(uri: string): Promise<vscode.Uri | null>

• validateAsmFile(uri: vscode.Uri, options?: { strict?: boolean }): Promise<vscode.Diagnostic[]>

• validateJsonFile(uri: vscode.Uri, options?: { strict?: boolean }): Promise<vscode.Diagnostic[]>

Notes:

• URI listing is directory-driven (workspace glob scanning plus any registered directory services) and returns resource IDs (e.g. PURLs), not local file: URIs.
• To open/read a listed resource, call resolveUri(id) to get an existing local file: URI (workspace file or downloaded .asm_cache/** file).
• URI resolution is resolution-driven (workspace-first, then HTTP download into .asm_cache/** with ETag/expiration handling).
• validateJsonFile(...) returns the extension's strict unknown-property diagnostics (and respects options.strict or the studioASM.validation.strict setting).

DirectoryService

Directory services provide resource ID listings (not file URIs). They are used by list*Uris() APIs and by schema/manifest lookup.

Shape:

export interface DirectoryService {
  /** Stable identifier for registry/de-dupe. */
  readonly id: string;
  readonly displayName: string;
  readonly kind: 'manifest' | 'schema' | 'shapes' | 'vocabulary';

  /** Lists resource IDs (URIs as strings) plus optional metadata. */
  listEntries(): Promise<Array<{ uri: string; size?: number; mtimeMS?: number; etag?: string }>>;

  /** Optional: refreshes an on-disk catalog/listing (must not download resource contents). */
  refresh?(folder: vscode.WorkspaceFolder): Promise<void>;
}

Guidelines:

• listEntries() should be best-effort and fast; it should not download resource contents.
• If your directory source needs network access, prefer implementing refresh() to update a listing/catalog, and keep listEntries() reading from that catalog.

ResolutionService

Resolution services map a resource ID (string URI) to a local VS Code URI (file:), downloading into .asm_cache/** if needed.

Shape:

export interface ResolutionService {
  /** Stable identifier for registry/de-dupe. */
  readonly id: string;
  readonly displayName: string;

  /** Returns a local VS Code URI, or null if the service does not apply. */
  resolveUri(uri: string): Promise<vscode.Uri | null>;
}

Guidelines:

• Your service will be considered for all URIs; return null quickly when it does not apply.
• Prefer workspace-first behavior when applicable, then cache-backed remote resolution.