System guidance

This page goes into more detail about technical concepts and other aspects of the system including material that may not be fully explained in the OpenAPI spec.

API resources

STARS is using REST APIs as its architectural style. The STARS API resource model aligns with the draft VET Information Standard (VET IS) to organise VET activity data into logical groupings that reflect how training organisations manage students and training. The model is designed as a flexible and modernised way to report Vocational Educational and Training (VET) data, replacing the current AVETMISS submission process based on NAT files.

Resources will utilise unique identifiers (see Immutable keys), managed by SMS providers, to allow updates in real time.

This model supports

• Incremental reporting and partial updates

• Early detection of data issues via provisional validation

• Reduced duplication (e.g. personal information sent only when changed)

• Stronger relational integrity between related records.

Resource operations

STARS uses standard HTTP methods to expose resources via API endpoints. For example, GET and POST operations will retrieve and create resources, respectively.

Uploading resources

Uploaded resources are held in STARS in a transaction batch until validated or submitted. At this stage, only the structure of the data is checked (format, identifiers, required fields). You can continue to add or replace records across resources (students, enrolments, offerings, etc.) in any order. Records are not treated as formally reported until final submission.

Top level resources

Top level resources are named after VET reporting concepts like student, program enrolment or delivery location. The naming logic reflects this. Top level resources may reference one another and can have child objects. The table below describes Stage 1 top level API resources.

Differences from AVETMISS

• Resources map to logical groupings instead of NAT files

• Addresses are structured as objects (permanent, term, postal) rather than single flat fields

• Supports progressive submission - no need for complete annual file compilation

Data uploads must include all child objects to date

When uploading a top‑level resource to STARS clients must always provide the complete set of associated child objects up to the present date.

STARS uses a full replacement (delete‑and‑insert) processing model for child objects. This means that any child objects not included in the upload payload will be treated as deleted, even if previously submitted.

For example, if the following was reported in 202501,

then while updating the conclusion in 202504, the complete set of all lifecycle states up to Dec 2025 must be uploaded

Request compression

Request compression enforcement is planned for a future release.

As at go-live, the following request size limits apply

· Maximum compressed request size: 1 MiB

· Maximum decompressed request size: 10 MiB

Requests that exceed the 10 MiB decompressed limit will be rejected with HTTP 413 (Payload Too Large) and the business rule error BRTS90400.

The compressed size limit is enforced as a protocol-level restriction and won’t return a Problem Details response.

Clients should ensure that the size of VET IS resource collections submitted in a single request remains configurable within their systems.

These limits reflect the current intended operating parameters and may be adjusted following further performance testing and operational review.

Reference data and system rules

STARS uses reference and classification data from external sources, including other NCVER systems, to deal with data. System rules are also explained further on this page.

No_value enumerations

Some VET IS reference lists include a No_value enum value. This value exists primarily to support client-side code generation, particularly where generated clients require a default value for non-nullable fields. No_value should not be treated as a reportable business value. Where a child object is optional, vendors should omit the child object when there is no applicable business value. Do not submit No_value to indicate “not applicable”, “unknown”, “not collected”, or “no data”.

From a STARS processing perspective, No_value has the same logical outcome as a null or no value being provided. If a child object is submitted, the required fields within that object must contain valid business values. Submitting No_value in place of a required business value may result in structural validation errors.

For example, if a training organisation has a third-party service provider involved in assessment or training for an enrolment, the thirdPartyServiceProviders child object should be submitted with a valid participantInvolvementType:

If there is no third-party service provider to report, do not submit:

Instead, omit the thirdPartyServiceProviders child object entirely.

^ Return to top

Minimal unit record

The minimal unit record (MUR) should be used as the first step in developing a client‑compatible integration with STARS. The MUR represents the “golden payloads” that are guaranteed to pass blocking validation, allowing SMS suppliers to focus on getting the core submission workflow working end‑to‑end before introducing more complex data scenarios.

This approach enables early verification that:

• transaction batches can be created and managed correctly,

• data can be uploaded and processed by STARS,

• validation services are functioning as expected, and

• successful submission can be completed and confirmed.

^ Return to top

Immutable keys

An immutable key is a UUID (universally unique identifier) that is system-generated and functions as a permanent identifier for a resource. Once created, it never changes, regardless of updates, transfers, or data resubmissions.

Immutable keys for STARS resources are to be created, stored, and managed by SMS suppliers.

All immutable keys must conform to the UUID v4 standard. For example: "studentUID": "550e8400-e29b-41d4-a716-446655440000"

SMS suppliers must:

1. Generate UUIDs for each resource when first created locally.

2. Persist these identifiers internally so that they remain stable across:

   • Resubmissions

   • Data corrections

   • Historical loads

   • Transfers between reporting periods

3. Send these UUIDs in all API payloads (POST, GET, DELETE) when referencing that entity.

4. Prevent reuse - if a record is deleted locally, its UUID must never be re-assigned.

5. Maintain mappings between business keys (e.g., USI, RTO Student ID) and immutable keys.

^ Return to top

Change tracking identifiers

A change tracking identifier is a client‑supplied opaque version token. A change tracking identifier is optional, and it represents the client’s notion of a specific version of a resource at the time it was uploaded to STARS.

It appears on all top‑level resources (for example: Student, DeliveryLocation, SubjectEnrolment, etc) and has the following characteristics:

• Client-generated
  The value is created and controlled by the calling system. The format and uniqueness are client defined.

• Opaque to STARS
  STARS does not interpret or modify the value.

• Echoed by the API
  The same value is returned in:

  • Upload responses

  • Validation results

  • Reconciliation endpoints

The change tracking identifier allows calling systems to deterministically match their local version of a resource with the version held by STARS, without STARS needing to understand the internal versioning logic of the client system.

How should calling systems use change tracking identifier?

• Assign a value when uploading or updating data
  When creating or updating a resource, include a change tracking identifier that reflects the version of the record in your system.

Example (Delivery Location upload):

Use it to confirm which version STARS has processed.

After upload, STARS returns the same identifier in its response:

This confirms that STARS has processed exactly the client’s version identified by the "changeTrackingIdentifier": "7fffght3-qwggdfgd"

Detect out‑of‑date data using reconciliation

Reconciliation endpoints return the change tracking identifier stored with previously submitted data.

This is the primary mechanism for determining whether STARS holds the current version of a resource.

Example reconciliation response (simplified):

The calling system can compare "changeTrackingIdentifier" value to its local version:

If local version is "3b6g-xd4k" → STARS is up to date

If local version is not "3b6g-xd4k" → STARS holds an older version and should be updated

This allows clients to avoid unnecessary re‑submissions and focus only on changed data.

It enables implementation of client controlled optimistic concurrency.

• Correlate validation errors back to your local data

Validation results also include the change tracking identifier. This allows the calling system to identify which local version of a record failed validation.

• Support reconciliation

Reconciliation endpoints return change tracking identifier values alongside resource UIDs and submission details. Calling systems can use this to:

• Compare previously submitted versions with current local versions

• Identify whether data has changed since last submission

• Detect re‑uploads of unchanged data

• Use it when voiding previously submitted data
  
  When requesting a void of previously submitted data (isVoided = true), the API optionally allows the change tracking identifier to be supplied:

 ^ Return to top

Transaction batch

A transaction batch is a container used to validate and submit data to STARS. It supports progressive submission, allowing training organisations to upload a single record or many related records, validate them and then formally submit the batch when ready.

All API paths for transactions batches are under /vet-provider/v1/{jurisdiction}/transaction-batch

Key points:

• A transaction batch can contain one or many records

• Transaction batches are validated as a whole

• Records in a transaction batch can be added, updated and/or removed before submission

• Transaction batches can be submitted or discarded without formal submission

• A jurisdiction is required when the batch is created and cannot be changed

^ Return to top

Errors and validation responses

Before data can be submitted, it must be validated against the STARS rules, which includes VET IS and system‑based validation rules implemented by STARS. Validation results contain findings produced by the STARS validation framework and have information to identify the affected resource, resource attributes, related validation results, and the scope of the validation failure.

^ Return to top

ProblemDetails

STARS APIs use RFC 9457 Problem Details responses to report request processing errors, including validation failures that prevent a request from being accepted. These may be returned for schema validation or domain validation failures.

^ Return to top

Pagination

STARS uses API pagination to break large amounts of retrieved data into smaller and more manageable chunks. Pagination parameters control how GET requests will return results. They will allow for specific subsets of data to be retrieved.

Endpoints supporting pagination

The following endpoints, and others, support pagination:

• GET /vet-provider/v1/transaction-batch retrieves a list of transaction batches

• GET /vet-provider/v1/transaction-batch/{transactionBatchToken}/failed-validation-results retrieves a list of failed validation results for a transaction batch.

Each VET IS resource now has a paged GET endpoint, for example:

• GET /vet-provider/v1/transaction-batch/{transactionBatchToken}/subjectoffering returns a paged response of SubjectOffering records.

QueryParameters

pageNumber: the page number to retrieve; type Integer

Default: 1, Minimum: 1, Maximum: 2147483647

pageSize: the number of results to return per page; type Integer

Default: 10, Minimum: 1, Maximum: 500

Best practice

Continue retrieving pages until all available results have been returned, rather than relying on a predefined maximum number of pages

^ Return to top

Whitespace validation rules

STARS applies strict structural validation to incoming data submitted via the STARS APIs.

This validation enforces allowable character‑set and whitespace rules across all string values to ensure data consistency and integrity. Requests that do not meet these requirements are rejected and are not persisted.

These rules apply consistently across string fields, with limited exceptions noted below.

Whitespace handling Rules

Leading and trailing spaces are not allowed.

If any string value includes leading or trailing spaces, the request will be rejected as structurally invalid.

For applicable string fields submitted via the STARS APIs:

• Leading spaces are not allowed

• Trailing spaces are not allowed

• Spaces within a value are allowed

Disallowed whitespace characters

The following whitespace characters are not permitted anywhere in string values:

• Tabs

• Line breaks (new lines or carriage returns)

• Non‑ASCII whitespace characters

If any of these characters are present, the request will be rejected as structurally invalid.

API response behaviour

When STARS detects invalid whitespace or non-permitted characters:

• The request is rejected with HTTP 400 – Bad Request

• The response is returned using the standard ProblemDetails format

• The affected data is not ingested or stored
  Clients should treat these response errors as schema or structural validation failures, not business rule errors.

Exception: enum values

Importantly, enum values are handled differently due to underlying .NET model-binding behaviour:

• Enum values may be submitted with leading or trailing spaces

• STARS will automatically trim enum values during processing

• These values may be accepted successfully

Recommendation

Clients should not rely on enum-specific trimming behaviour. All input values should be trimmed before submission to avoid unexpected validation failures.

^ Return to top

Rate limiting and concurrency

Rate limits are planned for a future release. Limits will be refined over time based on performance testing outcomes and observed client usage patterns. As a result, threshold values may change in future releases.

Rate limiting will be enforced at the protocol level and may occur on any API endpoint. Because it is not an application-level validation error, HTTP 429 responses are not currently described in the OpenAPI specification.

Clients should ensure that their integrations can detect and appropriately handle HTTP 429 responses, including implementing retry and back-off mechanisms where appropriate.

Request compression

Request compression enforcement is planned for a future release. As at go-live, the following request size limits apply:

• Maximum compressed request size: 1 MiB

• Maximum decompressed request size: 10 MiB

Requests that exceed the 10 MiB decompressed limit will be rejected with HTTP 413 (Payload Too Large) and the business rule error BRTS90400.

The compressed size limit is enforced as a protocol-level restriction and won’t return a Problem Details response.

Clients should ensure that the size of VET IS resource collections submitted in a single request remains configurable within their systems.

These limits reflect the current intended operating parameters and may be adjusted following further performance testing and operational review.