Micro-library for typing and validating UK tax identifiers.

v13.0 - 01 Aug 2025

• added additional Test Generators; now full coverage
• use the test jar to obtain the generators
• additional README clarifications

v12.0 - 15 April 2025

• remove support for scala 2.13
• remove support for play 2.8 and play 2.9
• update library dependencies

v11.0 - 17 Mar 2025

• update library dependencies

v10.0 - 17 Jun 2024

• add Scala 3.0 support. Remove Scala 2.12 support, noting Scala 2.13 is still supported.
• update library dependencies

v9.0 - 05 Dec 2023

• add support for Play 2.9 & Play 3.0, noting Play 2.8 is still supported
• update Scala 2.13 version
• update library dependencies
• add 'Change History' section to README

Types are provided for many common tax identifiers, such as:

• Employment Reference (EmpRef)
• National Insurance Number (NINO)
• Unique Taxpayer References (UTR) - Self Assessment, Corporation Tax, Annual Tax on Enveloped Dwellings, Pension Scheme Administrator ID, Pension Scheme Practitioner ID, Alcohol Wholesale Registration Scheme,
• Unique Agent Reference (UAR)
• VAT Registration Number (VRN)
• Economic Operators Registration and Identification (EORI)
• Agents - Code, UserId, PAYE Reference, Agent Business

Reads and Writes have been provided for Play's JSON library for all identifiers, and format validation is present for some. JSON objects with multiple tax identifiers as properties can be serialized or deserialized to a TaxIds:

import play.api.libs.json._
import uk.gov.hmrc.domain._

implicit val format: Format[TaxIds] = TaxIds.format(TaxIds.defaultSerialisableIds: _*)

val input =
  """{
    |"nino": "NM439088A",
    |"sautr": "some-sa-utr"
        }""".stripMargin
val taxIds = Json.parse(input).as[TaxIds]

taxIds.nino // Some(NM439088A)
taxIds.saUtr // Some(some-sa-utr)
taxIds.ctUtr // None

You must install the Test library to access the Test Generators. See further info in the Installing section

• AtedUtrGenerator - Rules for the AtedUtr: https://design.tax.service.gov.uk/hmrc-design-patterns/unique-taxpayer-reference/
• EoriGenerator - Rules for the EORI: https://design.tax.service.gov.uk/hmrc-design-patterns/eori-numbers/
• NinoGenerator - Rules for the Nino: https://en.wikipedia.org/wiki/National_Insurance_number#Format
• SaUtrGenerator - Rules for the SaUtr: https://design.tax.service.gov.uk/hmrc-design-patterns/unique-taxpayer-reference/
• VrnGenerator - Rules for the VRN: https://design.tax.service.gov.uk/hmrc-design-patterns/vat-registration-number/

val atedUtr = AtedUtrGenerator().nextAtedUtr.utr
val nino = NinoGenerator().nextNino.nino
val seed = 123456
val saUtr = SaUtrGenerator(seed).nextSaUtr.utr

"test example" in {
  val seed: Int = 734895
  val ninoGenerator: NinoGenerator = NinoGenerator(seed)
  val saUtrGenerator: SaUtrGenerator = SaUtrGenerator(seed)
  val nino: Nino = ninoGenerator.nextNino
  val saUtr: SaUtr = saUtrGenerator.nextSaUtr

  Nino.isValid(nino.nino)                           shouldBe true
  SelfAssessmentReferenceChecker.isValid(saUtr.utr) shouldBe true
}

1. Install the test library. See further info in the Installing section
2. Generator class has been broken into individual Named Generators

val generator = new Generator()
generator.nextNino
generator.atedUtrBatch(5)
generator.nextAtedUtr

is now

val ninoGenerator = NinoGenerator()
ninoGenerator.nextNino
val atedUtrGenerator = AtedUtrGenerator()
atedUtrGenerator.atedUtrBatch(5)
atedUtrGenerator.nextAtedUtr

Add the following to your SBT build:

libraryDependencies += "uk.gov.hmrc" %% "domain-play-[PLAY VERSION]" % "[LIB VERSION]"

or for the test library

libraryDependencies += "uk.gov.hmrc" %% "domain-test-play-[PLAY VERSION]" % "[LIB VERSION]" % Test

libraryDependencies += "uk.gov.hmrc" %% "domain-play-30" % "13.0.0"

or for the test library

libraryDependencies += "uk.gov.hmrc" %% "domain-test-play-30" % "13.0.0" % Test

sbt clean coverage test coverageReport

sbt publishLocal

This code is open source software licensed under the Apache 2.0 License.