YAML Spec

FNS spec - ver1.0_draft

Definition

This document describes the structure and composition that file and folder names should have. This specification is saved in YAML format.

Detailed specifications

Using ”---”, it must include at least 4 parts without omission and in the correct order.

---

### part1: Document description

TITLE: yaml example # Document title. Required field
FNS_VERSION: 1.0 # FNS spec version. Required field
date: 2020-01-01 # The remaining document fields can be freely added to describe this file. Key names must use lowercase.

---

### part2: Name and path patterns

- folder name: # Ending with ":" indicates it's a folder
  - subfolder name: # Tree structure is expressed with leading spaces
  - <pattern1>-<color> # Patterns are expressed using < and >
---

### part3: Actual examples that can be used for patterns defined in part1. Not required

color:["black","red","white"] # Stored as an array
---

### part4: Describes patterns defined in part1 that can be expressed as regular expressions

pattern1:'.+'

Custom pattern names must use lowercase. Uppercase patterns may be included in the specification (YYYY, MM, etc.)

Real examples

---

TITLE: yaml example
FNS_VERSION: 1.0
date: 2020-01-01

---

- Reports:
    - <YYYY>: # Year 2020 2021 2022 ...
        - <MM>: # Month 01 02 03 ...
            - <YYYYMMDD>-<TITLE>.xlsx # 20200101-Marketing Report.xlsx
- <INDEX01>-<routine_work>: # 02-Customer Management 03-Monitoring ...
- projects:
    - <project>: # Project Name
        - <task>:
            - <TITLE>-<task>-<project>-<YYYYMMDD>-v<ver>.<EXT> # Moon Landing Project Proposal-Planning-Moon Landing-20200101-v1.0.ppt

---

# The second area: lists examples of patterns that can be used.

task: ["Research", "Planning", "Development", "Release", "Marketing"]
project: ["MoonLanding", "MoonShot", "MoonWalking"]
EXT: ["pdf", "xlsx", "ppt"]

---

# In the third area: patterns that can be recognized by computers are described using regular expressions.

YYYYMMDD: '(?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])' # Date (Year-Month-Day)
YYYY: '(?:19|20)\d{2}' # Year 2019 2020 2021 ...
MM: "0[1-9]|1[0-2]" # Month 01 02 .. 12
INDEX01: "0[1-9]|[1-9][0-9]" # Number 01 02 03 ...
INDEX001: "0[0-9]{2}|[1-9][0-9]{2}" # Number 001 002 003 ...
ver: '(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?' # Version 1.0.0 Reference: https://github.com/nils-tekampe/semverdoc/blob/master/semverdoc.md
EXT: "[a-zA-Z0-9]{1,5}" # File extension pdf xlsx ppt ...

Storage location

FNS files are stored in ./.fns/index.yaml relative to the base folder. Example: documents/.fns/index.yaml, videos/.fns/index.yaml

FNS file validation

Must follow the YAML Spec.
Must include the following 4 documents:
1. First document: Document description
  - Must be a mapping with “TITLE” and “FNS_VERSION” keys (values must be string scalars)
2. Second document: File and path patterns
  - Top-level items must be block sequences
  - Block sequences can contain mappings (representing subfolders) or string scalars (representing files)
  - Mappings must have exactly one key, which stores the subfolder name
  - Mapping values must be either block sequences (for subfolders with content) or empty (for empty folders)
3. Third document: Pattern examples
  - Can contain multiple mappings with key (pattern name) and value pairs. The value contains an array of string scalars (examples of strings that match the pattern)
4. Fourth document: Regular expressions for patterns
  - Can contain multiple mappings with key (pattern name) and value pairs. The value contains a string scalar (regular expression that recognizes the pattern)

Contributing

For questions or feedback, you can participate in the discussions.