National Document Validator

A Go library for validating, parsing, and working with national identity documents from various countries.

Features

• Multi-Country Support: Easily extensible to support new countries.
• Validation: Check if a document number is valid.
• Normalization: Convert document numbers into a standard, clean format.
• Masking: Mask document numbers for privacy (e.g., for logging or UI).
• Data Extraction: Extract available information from a document number (e.g., type, approximate birth period).
• Generation: Generate random, valid document numbers for testing and development.
• Comparison: Compare two document numbers, ignoring formatting differences.

Installation

To install the package, use go get:

go get github.com/ELadrimonos/national-document-validator

Usage

Here is a complete example of how to use the library:

package main

import (
	"fmt"

	"github.com/ELadrimonos/national-document-validator/validators"
	"github.com/ELadrimonos/national-document-validator/validators/ar" // Argentina
	"github.com/ELadrimonos/national-document-validator/validators/es" // Spain
)

func main() {
	// 1. Create a new validator instance
	v := validators.NewValidator()

	// 2. Register the validators for the countries you need
	v.Register("es", &es.ESValidator{})
	v.Register("ar", &ar.ARValidator{})

	// --- Example: Validate a Spanish DNI ---
	fmt.Println("--- Spain (ES) ---")
	docES := "87.654.321-R"
	err := v.Validate("es", docES)
	if err != nil {
		fmt.Printf("Document '%s' is invalid: %v\n", docES, err)
	} else {
		fmt.Printf("Document '%s' is valid.\n", docES)
	}

	// --- Example: Mask a document ---
	maskedDoc, err := v.Mask("es", docES)
	if err != nil {
		fmt.Printf("Could not mask document: %v\n", err)
	} else {
		fmt.Printf("Masked document: %s\n", maskedDoc)
	}

	// --- Example: Compare two documents ---
	fmt.Println("\n--- Comparison Example (ES) ---")
	doc1 := "87.654.321-R"
	doc2 := "87654321R"
	areEqual, err := v.Compare("es", doc1, doc2)
	if err != nil {
		fmt.Printf("Could not compare documents: %v\n", err)
	} else if areEqual {
		fmt.Printf("Documents '%s' and '%s' are equal.\n", doc1, doc2)
	}

	// --- Example: Generate a random document ---
	fmt.Println("\n--- Generation Example (AR) ---")
	generatedDoc, err := v.Generate("ar")
	if err != nil {
		fmt.Printf("Could not generate document: %v\n", err)
	} else {
		fmt.Printf("Generated Argentinian DNI: %s\n", generatedDoc)
		// You can then validate the generated document
		err = v.Validate("ar", generatedDoc)
		fmt.Printf("Validation of generated DNI: %v (nil means valid)\n", err)
	}
}

Supported Countries

• ES - Spain (DNI and NIE)
• AR - Argentina (DNI)

Enabling Countries

This library is designed to be modular. You only need to include the code for the countries you are going to use, which keeps your application's size minimal.

To use a country's validator, you need to:

1. Import the specific country package.
2. Register it with your validator instance.

Here is how you would enable validation for Spain (es) and Argentina (ar):

import (
    "github.com/ELadrimonos/national-document-validator/validators"
    "github.com/ELadrimonos/national-document-validator/validators/ar" // Import Argentina
    "github.com/ELadrimonos/national-document-validator/validators/es" // Import Spain
)

// ...

// Create a new validator instance
v := validators.NewValidator()

// Register the validators for the countries you need
v.Register("es", &es.ESValidator{})
v.Register("ar", &ar.ARValidator{})

Contributing

If you want to contribute by adding support for a new country, the process is straightforward:

1. Create a new package under the validators directory (e.g., validators/fr for France).
2. Inside the new package, create a Validator struct (e.g., FRValidator) that implements the validators.DocumentValidator interface.
3. Submit a pull request.

API Overview

The main Validator object provides the following methods:

• NewValidator() *Validator: Creates a new validator instance.
• Register(countryCode string, validator DocumentValidator): Registers a country-specific validator.
• Validate(countryCode, doc string) error: Validates a document.
• Mask(countryCode, doc string) (string, error): Masks a document.
• Compare(countryCode, doc1, doc2 string) (bool, error): Compares two documents.
• GetType(countryCode, doc string) (string, error): Gets the document type (e.g., "DNI", "NIE").
• ExtractInfo(countryCode, doc string) (map[string]interface{}, error): Extracts information from the document.
• Generate(countryCode string) (string, error): Generates a new valid document number.