ISO duration structure check

iso-duration-structure-check · version 1.0.0 · Dates & times (UTC, ISO 8601) · free, no key needed

Check a claimed reading of an ISO 8601 duration: well-formedness, components and month/day/time totals.

Use when you need to: check if an iso 8601 duration string is valid · verify parsed duration components · is P1M one month or one minute.

Decide before calling

Read the versioned contract and the supported scope below. Reuse iso-duration-structure-check@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use iso-duration-structure-check@1.0.0 for check if an iso 8601 duration string is valid. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

• check if an iso 8601 duration string is valid
• verify parsed duration components
• is P1M one month or one minute
• validate rfc 3339 duration syntax
• check claimed total months and days of a duration
• find where an iso duration string is malformed
• confirm duration hours minutes seconds breakdown

Not supported

• negative or signed durations (ISO 8601-2 extension, -P1D)
• the alternative format PYYYY-MM-DDThh:mm:ss
• converting calendar months or days to seconds
• time intervals with start/end solidus notation

Behavior

• Reference: ISO 8601-1:2019 duration representations with designators (PnYnMnDTnHnMnS, PnW) and RFC 3339 Appendix A duration ABNF; reference_version is returned with every result.
• profile "iso8601-1-2019": P, then either nW alone or date components Y, M, D in that order and optionally T with H, M, S in that order; zero components may be omitted but at least one must be present; T only when a time component follows; only the last component may carry a decimal fraction with "," or ".".
• profile "rfc3339-appendix-a": the RFC 3339 ABNF: integer components only, contiguous runs (Y[M[D]], M[D], D; H[M[S]], M[S], S) or nW alone.
• claim.well_formed is required. With false no other claim field is allowed and the check passes only when the text is not a duration of the profile.
• Syntax failure reports position: the index in code points of the first code point at which the text stops being a prefix of any well-formed duration, or the text length when it ends early (reason syntax_error).
• Component claims (years, months, weeks, days, hours, minutes, seconds) are exact non-negative decimals compared by value; an absent component is 0.
• Derived claims keep calendar and elapsed time separate: calendar_months = 12 * years + months, calendar_days = 7 * weeks + days, time_nanoseconds = 10^9 * (3600 * hours + 60 * minutes + seconds), exact decimals.
• Comparison order: well_formed, years, months, weeks, days, hours, minutes, seconds, calendar_months, calendar_days, time_nanoseconds; actual values are canonical decimals (no leading or trailing zeros, "." as decimal sign).

Input

• duration (string, required): max length 100
• profile (one of "iso8601-1-2019", "rfc3339-appendix-a", required)
• claim (object, required)

Output

• valid (boolean, required)
• reason (one of null, "syntax_error", "well_formed_mismatch", "component_mismatch", "derived_mismatch", required)
• first_discrepancy (object or null, required)
• profile (one of "iso8601-1-2019", "rfc3339-appendix-a", required)
• reference_version (string, required)

Limits

• max duration chars: 100
• max claim chars: 100

Example

Request input:

{
  "duration": "P3Y6M4DT12H30M5S",
  "profile": "iso8601-1-2019",
  "claim": {
    "well_formed": true,
    "years": 3,
    "months": 6,
    "days": 4,
    "hours": 12,
    "minutes": 30,
    "seconds": 5,
    "calendar_months": 42
  }
}

Response:

{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "profile": "iso8601-1-2019",
    "reference_version": "ISO 8601-1:2019 durations (designator format) + RFC 3339 (2002) timestamps; r66-duration-claim-verifiers@1.0.0"
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "iso-duration-structure-check",
  "version": "1.0.0",
  "input": {
    "duration": "P3Y6M4DT12H30M5S",
    "profile": "iso8601-1-2019",
    "claim": {
      "well_formed": true,
      "years": 3,
      "months": 6,
      "days": 4,
      "hours": 12,
      "minutes": 30,
      "seconds": 5,
      "calendar_months": 42
    }
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/iso-duration-structure-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"duration":"P3Y6M4DT12H30M5S","profile":"iso8601-1-2019","claim":{"well_formed":true,"years":3,"months":6,"days":4,"hours":12,"minutes":30,"seconds":5,"calendar_months":42}}'

The machine-readable contract is at /v1/tools/iso-duration-structure-check/versions/1.0.0.

CLI

node cli.mjs run iso-duration-structure-check 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Related tools

• Duration application check: Check a claimed timestamp from adding or subtracting an ISO 8601 duration under explicit offset and month-end rules.
• Duration convert: Convert a canonical integer duration between nanosecond-based SI units as an exact rational.
• Appointment request check: Check an appointment request against pinned time-zone facts and caller-supplied booking rules.
• ISO date days in month: Return the number of calendar days in a given proleptic Gregorian year and month.
• ISO date is business day: Test whether a date is a business day given caller-supplied weekend weekdays and holiday dates.
• ISO date is leap year: Test whether a proleptic Gregorian calendar year is a leap year.