Skip to content

Commit cc7ba93

Browse files
devpratondevpraton
committed
Initial draft
1 parent e0d4147 commit cc7ba93

File tree

6 files changed

+238
-31
lines changed

6 files changed

+238
-31
lines changed

‎spec/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ out_dir:
99
@mkdir -p $(OUTPUT)
1010

1111
$(OUTPUT)/%.pdf: %.tex spec.cls | out_dir
12-
@tectonic -Z shell-escape $< -o out/
12+
@tectonic -c minimal -X compile $< -o out/
1313
@echo "GEN $@"
1414

1515
clean:

‎spec/example_ucf.tex‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11

2-
\begin{minted}[bgcolor=black!5]{toml}
2+
\section{Example UCF File}
3+
4+
\begin{lstlisting}[language=bash]
35

46
# ========================
57
# UNIVERSAL COMPLAINT FILE
@@ -28,8 +30,6 @@
2830
[location]
2931
method = "url" # url / coordinates
3032
url = "https://maps.app.goo.gl/8fwXBzzBW4oocjth7"
31-
latitude = "13.00753"
32-
longitude = "77.65592"
3333

3434
[[attachment-details]]
3535
url = "https://photos.app.goo.gl/4MsLGvJeGZoWUyL67"
@@ -43,4 +43,4 @@
4343
last-updated = "2025-10-22T17:25:00+05:30"
4444
tracker-link = "" # optional, if public tracking available
4545

46-
\end{minted}
46+
\end{lstlisting}

‎spec/section_descriptions.tex‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
2+
\section{Mandatory sections}
3+
4+
\begin{spectable}{Section}{Purpose}
5+
\spectablerow{[ucf-meta]}{Meta-information about file version, generator, timestamps}
6+
\spectablerow{[complainant-details]}{Citizen identity and contact details}
7+
\spectablerow{[complaint-details]}{Core complaint description and classification}
8+
\spectablerow{[location]}{Location of the issue (as coordinates or link)}
9+
\spectablerow{[[attachment-details]]}{List of zero or more attachments (image, video, etc.)}
10+
\spectablerow{[complaint-status]}{Complaint state and optional status notes}
11+
\end{spectable}
12+
13+
\section{Mandatory sections descriptions}
14+
15+
\subsection{[ucf-meta]}
16+
17+
Metadata describing this UCF file.
18+
19+
\begin{specsubtable}{Key}{Type}{Required}{Description}
20+
\specsubtablerow{version}{string}{yes}{UCF specification version (e.g., "0.2")}
21+
\specsubtablerow{generated-at}{datetime (RFC 3339)}{yes}{UTC or local datetime of file creation}
22+
\specsubtablerow{source-app}{string}{yes}{Name or identifier of the application that generated this file}
23+
\end{specsubtable}
24+
25+
Example:
26+
\medskip
27+
\begin{lstlisting}[language=bash]
28+
[ucf-meta]
29+
version = "0.2"
30+
generated-at = "2025-10-22T17:30:00+05:30"
31+
source-app = "MyCitizenApp"
32+
\end{lstlisting}
33+
34+
\subsection{[complainant-details]}
35+
36+
Basic details about the complainant (sometimes auto-populated).
37+
38+
\begin{specsubtable}{Key}{Type}{Required}{Description}
39+
\specsubtablerow{name}{string}{yes}{Full name of complainant}
40+
\specsubtablerow{contact}{string}{yes}{Primary contact number}
41+
\specsubtablerow{email}{string}{no}{Optional email address}
42+
\specsubtablerow{auth-id}{string}{no}{Unique identifier (ID from authentication system)}
43+
\end{specsubtable}
44+
45+
Example:
46+
\medskip
47+
\begin{lstlisting}[language=bash]
48+
[complainant-details]
49+
name = "ABC Kumar"
50+
contact = "1234567890"
51+
email = "[email protected]"
52+
auth-id = "citizen_02349"
53+
\end{lstlisting}
54+
55+
\subsection{[complaint-details]}
56+
57+
Core description of the issue and the department responsible.
58+
59+
\begin{specsubtable}{Key}{Type}{Required}{Description}
60+
\specsubtablerow{description}{string}{yes}{Human-readable complaint text}
61+
\specsubtablerow{category}{string}{no}{Complaint theme (sanitation, traffic, etc.)}
62+
\specsubtablerow{department}{string}{yes}{Target department identifier}
63+
\specsubtablerow{priority}{string}{no}{One of low, normal, high}
64+
\specsubtablerow{submission-method}{string}{yes}{Originating platform: app, web, kiosk, helpline, etc.}
65+
\specsubtablerow{attachment}{boolean}{yes}{Whether this complaint has one or more attachments}
66+
\specsubtablerow{ticket-id}{string}{no}{assigned id by the generation system}
67+
\end{specsubtable}
68+
69+
Example:
70+
\medskip
71+
\begin{lstlisting}[language=bash]
72+
[complaint-details]
73+
description = "Garbage not cleaned for 3 days"
74+
category = "sanitation"
75+
department = "bbmp"
76+
priority = "normal"
77+
submission-method = "app"
78+
attachment = true
79+
\end{lstlisting}
80+
81+
\subsection{[location]}
82+
83+
Defines the place related to the complaint.
84+
85+
\begin{specsubtable}{Key}{Type}{Required}{Description}
86+
\specsubtablerow{method}{string}{yes}{How the location is represented: url or coordinates}
87+
\specsubtablerow{url}{string}{conditional}{Required if method = "url"}
88+
\specsubtablerow{latitude}{float}{conditional}{Required if method = "coordinates"}
89+
\specsubtablerow{longitude}{float}{conditional}{Required if method = "coordinates"}
90+
\end{specsubtable}
91+
92+
Example:
93+
\medskip
94+
\begin{lstlisting}[language=bash]
95+
[location]
96+
method = "coordinates"
97+
latitude = 13.00753
98+
longitude = 77.65592
99+
\end{lstlisting}
100+
101+
\subsection{[[attachment-details]]}
102+
103+
An array of tables, each describing a single attachment.
104+
If no attachments exist, this section may be omitted.
105+
106+
\begin{specsubtable}{Key}{Type}{Required}{Description}
107+
\specsubtablerow{url}{string}{yes}{Publicly accessible or signed media link}
108+
\specsubtablerow{file-type}{string}{yes}{MIME type (image/jpeg, video/mp4, etc.)}
109+
\specsubtablerow{description}{string}{no}{Short textual note about attachment}
110+
\specsubtablerow{hash}{string}{no}{MD5 or SHA256 hash for integrity verification}
111+
\end{specsubtable}
112+
113+
Example:
114+
\medskip
115+
\begin{lstlisting}[language=bash]
116+
[[attachment-details]]
117+
url = "https://photos.app.goo.gl/4MsLGvJeGZoWUyL67"
118+
file-type = "image/jpeg"
119+
description = "Garbage pile photo"
120+
hash = "b1946ac92492d2347c6235b4d2611184"
121+
122+
[[attachment-details]]
123+
url = "https://audio.example.org/complaint-note.mp3"
124+
file-type = "audio/mpeg"
125+
description = "Voice note describing complaint"
126+
hash = "ad0234829205b9033196ba818f7a872b"
127+
\end{lstlisting}
128+
129+
\subsection{[complaint-status]}
130+
131+
Describes current status of the complaint process.
132+
133+
\begin{specsubtable}{Key}{Type}{Required}{Description}
134+
\specsubtablerow{status}{string}{yes}{One of: submitted, in-process, closed}
135+
\specsubtablerow{comment}{string}{no}{Optional remarks from operator or system}
136+
\specsubtablerow{last-updated}{datetime}{no}{Last modification timestamp}
137+
\specsubtablerow{tracker-link}{string}{no}{External link to track live progress}
138+
\end{specsubtable}
139+
140+
Example:
141+
\medskip
142+
\begin{lstlisting}[language=bash]
143+
[complaint-status]
144+
status = "submitted"
145+
comments = ""
146+
last-updated = "2025-10-22T17:32:00+05:30"
147+
tracker-link = ""
148+
\end{lstlisting}
149+
150+
\section{Optional Extensions}
151+
152+
Departments or applications may define additional sections using custom tables,
153+
each new table should use either a prefix naming scheme ([custom.<name>]) or
154+
include a namespace hint to avoid collision.

‎spec/spec.cls‎

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,17 @@
1414
\usepackage[top=1in, bottom=0.5in, left=0.75in, right=0.75in]{geometry}
1515
\usepackage{graphicx}
1616
\usepackage{array}
17+
\usepackage{listings}
18+
\lstdefinestyle{speclistingstyle}{
19+
basicstyle=\ttfamily, % Standardschrift
20+
numbers=left, % Ort der Zeilennummern
21+
numberstyle=\tiny, % Stil der Zeilennummern
22+
aboveskip= 0pt,
23+
emphstyle=\textbf,
24+
frame=single
25+
}
26+
27+
\lstset{style=speclistingstyle}
1728

1829
% Increase the space between table rows
1930
\renewcommand{\arraystretch}{1}
@@ -40,7 +51,8 @@
4051
% Reference to last page number
4152
\usepackage{lastpage}
4253

43-
\usepackage{lmodern}
54+
\usepackage{verbatim}
55+
\usepackage{fancybox}
4456

4557
\usepackage{fontspec}
4658
\setmainfont{texgyrepagella}[
@@ -218,7 +230,6 @@
218230
\textbf{#1} & \textbf{#2} \\
219231
\midrule
220232
}{
221-
\bottomrule
222233
\end{longtable}
223234

224235
% Fixed vertical whitespace in case the table uses up all the stretch space
@@ -229,8 +240,39 @@
229240
% SPEC TABLE ROW DEFINITION
230241
%----------------------------------------------------------------------------------------
231242
% Arguments: 1) description 2) quantity 3) unit price 4) note
232-
\newcommand{\spectabelrow}[2]{%
243+
\newcommand{\spectablerow}[2]{%
233244
#1 & #2 \\
245+
\midrule
246+
}
247+
248+
%----------------------------------------------------------------------------------------
249+
% SPEC SUBTABLE ENVIRONMENT
250+
%----------------------------------------------------------------------------------------
251+
\newenvironment{specsubtable}[4]{
252+
\renewcommand{\arraystretch}{1.5}
253+
% Fixed vertical whitespace in case the table uses up all the stretch space
254+
\vspace{0.02\textheight} %
255+
256+
% Define table column widths and alignments (L, R or C for left, right or center alignment)
257+
\begin{longtable}[H]{@{} L{0.15\textwidth} L{0.10\textwidth} L{0.10\textwidth} L{0.50\textwidth}}%
258+
\toprule
259+
% Header row
260+
\textbf{#1} & \textbf{#2} & \textbf{#3} & \textbf{#4} \\
261+
\midrule
262+
}{
263+
\end{longtable}
264+
265+
% Fixed vertical whitespace in case the table uses up all the stretch space
266+
\vspace{0.02\textheight}
267+
}
268+
269+
%----------------------------------------------------------------------------------------
270+
% SPEC SUBTABLE ROW DEFINITION
271+
%----------------------------------------------------------------------------------------
272+
% Arguments: 1) col-1 2) col-2 3) col-3 4) col-4
273+
\newcommand{\specsubtablerow}[4]{%
274+
#1 & #2 & #3 & #4\\
275+
\midrule
234276
}
235277

236278
%----------------------------------------------------------------------------------------
@@ -270,6 +312,15 @@
270312
\end{itemize}
271313
}
272314

315+
%----------------------------------------------------------------------------------------
316+
% SPEC LISTING DEFINITION
317+
%----------------------------------------------------------------------------------------
318+
\newenvironment{speclisting}{
319+
\begin{verbatim}
320+
}{
321+
\end{verbatim}
322+
}
323+
273324
%----------------------------------------------------------------------------------------
274325
% SPEC TITLE DEFINITION
275326
%----------------------------------------------------------------------------------------

‎spec/spec.tex‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11

22
\documentclass[12pt]{spec}
33

4-
\usepackage{minted}
5-
64
\begin{document}
75

86
\specheader
@@ -11,6 +9,8 @@
119

1210
\spectitle{Universal Complaint Format Specification}{VERSION: v0.1}
1311

12+
\section{Overview}
13+
1414
\specjust{A standardized open-source TOML-based format for registering generic
1515
complaints against public or private entities. This format
1616
is \textbf{citizen-facing} and focuses on interoperability across different
@@ -20,23 +20,25 @@
2020

2121
\input{structure.tex}
2222

23-
\section{Mandatory sections}
24-
\begin{spectable}{Section}{Purpose}
25-
\spectabelrow{[ucf-meta]}{Meta-information about file version, generator, timestamps}
26-
\spectabelrow{[complainant-details]}{Citizen identity and contact details}
27-
\spectabelrow{[complaint-details]}{Core complaint description and classification}
28-
\spectabelrow{[location]}{Location of the issue (as coordinates or link)}
29-
\spectabelrow{[[attachment-details]]}{List of zero or more attachments (image, video, etc.)}
30-
\spectabelrow{[complaint-status]}{Complaint state and optional status notes}
31-
\end{spectable}
32-
33-
\newpage
23+
\input{section_descriptions.tex}
24+
25+
% TODO: wrap this in a box
3426
\input{example_ucf.tex}
3527

36-
\section{[ucf-meta]}
28+
\section{Compliance}
29+
30+
A file is considered UCF-compliant if:
3731

38-
Metadata describing this UCF file.
32+
\begin{itemize}
33+
\item It conforms to TOML v1.0.0.
34+
\item It includes the mandatory sections and required keys.
35+
\item Datetime should be RFC 3339 formatted.
36+
\item Booleans should be lowercase true/false.
37+
\item Optional sections, if present, respect type and naming rules.
38+
\item Arrays: Only [[]] are allowed for repeated structures (attachments)
39+
\end{itemize}
3940

41+
\section{FAQs}
4042
\begin{specpara}{Why TOML?}
4143

4244
\href{https://toml.io/en}{TOML} is human-readable, simple, and supported across many
@@ -46,7 +48,8 @@ \section{[ucf-meta]}
4648

4749
\end{specpara}
4850

49-
\begin{specitemize}{Additional Notes}
51+
\section{Notes}
52+
\begin{specitemize}{Features}
5053

5154
\item Autopopulation: Apps can automatically fill fields
5255
like `name`, `contact`, `location`, and `auth-id` from user profiles and device

‎spec/structure.tex‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11

2-
\begin{specitemize}{General structure}
2+
\section{General structure}
33

4-
\item A \textit{.ucf} file is a valid TOML document in `UTF-8` encoding, containing multiple
5-
table sections. Each section describes a logical part of the complaint.
4+
A \textit{.ucf} file is a valid TOML document in `UTF-8` encoding, containing
5+
multiple table sections. Each section describes a logical part of the
6+
complaint.
67

7-
\item Each complaint corresponds to one \textit{.ucf} file. Comments begin with \# and may
8-
appear anywhere outside strings.
9-
10-
\end{specitemize}
8+
Each complaint corresponds to one \textit{.ucf} file. Comments begin with \#
9+
and may appear anywhere outside strings.

0 commit comments

Comments
 (0)